• unscramble_taxon
• parse_nftoken_id

Sources:

• https://github.com/XRPLF/xrpl-py/blob/b7dfe759bd2174339542a87f40b1784456061eeb/xrpl/utils/parse_nftoken_id.py

The fields of the most important models (e.g. requests or transactions) should be well documented. We should add docstrings for each field, describing what its purpose is.

Docstrings for the transactions will be merged with #9

The user should not have to set the type of a request or a transaction. Instead the type could simply be added when calling the to_json_value method of the Model trait.

I am writing xrpl_async Rust library.

I implemented a good async interface common for both JSON RPC and WebSocket APIs. I also implemented some WebSocket waiter tweaks. Thus your task of "Asynchronous ledger interactions" and is to be counted done.

Also I create "Models" instead of you.

I import your library for {decode,encode}_base58.

I propose to join efforts: xrpl-rust for low-level stuff and xrpl_async for high-level. Agree?

I am now trying to serialize transactions. Ideally it would be like this:

#[derive(Serialized)]
struct Transaction {
    #[serialized_as(nth = ...)] // The rest serialization properties belong to `Address` type
    account: Address,
    // ...
}

Then the Rust macro implementation can sort fields to correct order.

Your serialization seems to use string representations of types, what is not idiomatic Rust. I am now thinking about creating such macro wrapper around your serialization functions. Please, give me a clue: What is the most high-level way to serialize with xrpl-rust? (I think it's the one described here, but I am unsure if it's the highest level of your library, by the way it uses string representations of types, what is not idiomatic Rust.)

So, how will we collaborate?

Currently there is no official documentation. Research still needs to be done. We can use xrpl-py as a reference.
Sources:

• https://github.com/XRPLF/xrpl-py/pulls?q=is%3Apr+sidechain
• XRPLF/xrpl-py#417

To avoid confusion the field structs like Directory, DepositPreauth, Offer, etc., which are currently defined in mod.rs, should be separated to a new file. There are Ledger Objects that have the same name but different fields. Also there is a DepositPreauth transaction.

I separated them in #9 for now.

serde_cbor is unmaintained

The serde_cbor crate is unmaintained. The author has archived the github repository.

Alternatives proposed by the author:

*ciborium
*minicbor

See advisory page for additional details.

We should have an own directory for the transactions and put the types in separate files. This really improves the library’s structure.

• TODO: keep an eye on the XRPFees amendment. It could change how some fields are typed and/or named.

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:

    • ...

All ledger object models have to be deserializable from json.

• A LedgerEntryType enum

• AccountRoot

  1. The AccountRoot object type describes a single account, its settings, and XRP balance.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::AccountRoot	An indicator of what type of object it is.
  account	&str	The identifying (classic) address of this account.
  balance	&str	The account's current XRP balance in drops, represented as a string.
  flags	u32	A bit-map of boolean flags enabled for this account.
  owner_count	u32	The number of objects this account owns in the ledger, which contributes to its owner reserve.
  previous_txn_id	&str	The identifying hash of the transaction that most recently modified this object.
  previous_txn_lgr_seq	u32	The index of the ledger that contains the transaction that most recently modified this object.
  sequence	u32	The sequence number of the next valid transaction for this account.
  account_txn_id	Option<&str>	The identifying hash of the transaction most recently sent by this account.
  burned_nftokens	Option<u32>	How many total of this account's issued non-fungible tokens have been burned.
  domain	Option<&str>	A domain associated with this account.
  email_hash	Option<&str>	The md5 hash of an email address.
  message_key	Option<&str>	A public key that may be used to send encrypted messages to this account.
  minted_nftokens	Option<u32>	How many total non-fungible tokens have been minted by and on behalf of this account.
  nftoken_minter	Option<&str>	Another account that is authorized to mint non-fungible tokens on behalf of this account.
  regular_key	Option<&str>	The address of a key pair that can be used to sign transactions for this account instead of the master key.
  ticket_count	Option<u32>	How many Tickets this account owns in the ledger.
  ticket_size	Option<u8>	How many significant digits to use for exchange rates of Offers involving currencies issued by this address.
  transfer_rate	Option<u32>	A transfer fee to charge other users for sending currency issued by this account to each other.
  wallet_locator	Option<&str>	DEPRECATED but may be relevant because of: https://xrpl.org/multi-signing.html#wallet-locator
  wallet_size	Option<u32>	DEPRECATED but may be relevant because of: https://xrpl.org/multi-signing.html#wallet-locator

  Sources:

  • https://xrpl.org/accountroot.html

• Amendments

  1. The Amendments object type contains a list of Amendments that are currently active.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::Amendments	An indicator of what type of object it is.
  flags	u32	A bit-map of boolean flags.
  amendments	Option<Vec<&str>>	Array of 256-bit amendment IDs for all currently-enabled amendments.
  majorities	Option<Vec<Majority>>	Array of objects describing the status of amendments that have majority support but are not yet enabled.

  Sources:

  • https://xrpl.org/amendments-object.html

  • Majority

    1. An object describing the status of an amendment that has majority support but is not yet enabled.

    3. It could be represented as follows:

       #[derive(Debug, Serialize, Deserialize)]
       #[serde(rename_all("PascalCase"))]
       pub enum MajorityWrapper<'a> {
           Majority {
               amendment: &'a str,
               close_time: u32
           }
       }

    fields	type	explanation
    amendment	&str	The Amendment ID of the pending amendment.
    close_time	u32	The close_time field of the ledger version where this amendment most recently gained a majority.

    Sources:

    • https://xrpl.org/amendments-object.html

• Check

  1. A Check object describes a check, similar to a paper personal check, which can be cashed by its destination to get money from its sender.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::AccountRoot	An indicator of what type of object it is.
  account	&str	The sender of the Check.
  destination	&str	The intended recipient of the Check.
  flags	u32	A bit-map of boolean flags.
  owner_node	&str	A hint indicating which page of the sender's owner directory links to this object, in case the directory consists of multiple pages.
  previous_txn_id	&str	The identifying hash of the transaction that most recently modified this object.
  previous_txn_lgr_seq	u32	The index of the ledger that contains the transaction that most recently modified this object.
  send_max	Currency	The maximum amount of currency this Check can debit the sender.
  sequence	u32	The sequence number of the CheckCreate transaction that created this check.
  destination_node	Option<&str>	A hint indicating which page of the destination's owner directory links to this object, in case the directory consists of multiple pages.
  destination_tag	Option<u32>	An arbitrary tag to further specify the destination for this Check, such as a hosted recipient at the destination address.
  expiration	Option<u32>	ndicates the time after which this Check is considered expired. See Specifying Time for details.
  invoice_id	Option<&str>	Arbitrary 256-bit hash provided by the sender as a specific reason or identifier for this Check.
  source_tag	Option<&str>	An arbitrary tag to further specify the source for this Check, such as a hosted recipient at the sender's address.

• DepositPreauth

  1. A DepositPreauth object tracks a preauthorization from one account to another.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::DepositPreauth	An indicator of what type of object it is.
  account	&str	The account that granted the preauthorization.
  authorize	&str	The account that received the preauthorization.
  flags	u32	A bit-map of boolean flags. No flags are defined for DepositPreauth objects, so this value is always 0.
  owner_node	&str	A hint indicating which page of the sender's owner directory links to this object, in case the directory consists of multiple pages.
  previous_txn_id	&str	The identifying hash of the transaction that most recently modified this object.
  previous_txn_lgr_seq	&str	The index of the ledger that contains the transaction that most recently modified this object.

  Sources:

  • https://xrpl.org/directorynode.html

• DirectoryNode

  1. The DirectoryNode object type provides a list of links to other objects in the ledger's state tree.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::DirectoryNode	An indicator of what type of object it is.
  flags	u32	A bit-map of boolean flags enabled for this directory.
  root_index	&str	The ID of root object for this directory.
  indexes	Vecy<u32>	An array of IDs of other objects.
  index_next	Option<u32>	If this Directory consists of multiple pages, this ID links to the next object in the chain, wrapping around at the end.
  index_previous	Option<u32>	If this Directory consists of multiple pages, this ID links to the previous object in the chain, wrapping around at the beginning.
  owner	Option<&str>	The address of the account that owns the objects in this directory.
  exchange_rate	Option<u32>	The quality of an offer. DEPRECATED
  taker_pays_currency	Option<&str>	The currency code of the TakerPays amount from the offers in this directory.
  taker_pays_issuer	Option<&str>	The issuer of the TakerPays amount from the offers in this directory.
  taker_gets_currency	Option<&str>	The currency code of the TakerGets amount from the offers in this directory.
  taker_gets_issuer	Option<&str>	The issuer of the TakerGets amount from the offers in this directory.

  Sources:

  • https://xrpl.org/directorynode.html

• Escrow

  1. The Escrow object type represents a held payment of XRP waiting to be executed or canceled.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::Escrow	An indicator of what type of object it is.
  account	&str	The address of the owner (sender) of this held payment.
  flags	u32	A bit-map of boolean flags. No flags are defined for the Escrow type, so this value is always 0.
  destination	&str	The destination address where the XRP is paid if the held payment is successful.
  amount	&str	The amount of XRP, in drops, to be delivered by the held payment.
  owner_node	&str	A hint indicating which page of the owner directory links to this object, in case the directory consists of multiple pages.
  previous_txn_id	&str	The identifying hash of the transaction that most recently modified this object.
  previous_txn_lgr_seq	u32	The index of the ledger that contains the transaction that most recently modified this object.
  condition	Option<&str>	A PREIMAGE-SHA-256 crypto-condition , as hexadecimal.
  cancel_after	Option<u32>	The held payment can be canceled if and only if this field is present and the time it specifies has passed.
  finish_after	Option<u32>	The time, in seconds since the Ripple Epoch, after which this held payment can be finished.
  source_tag	Option<u32>	An arbitrary tag to further specify the source for this held payment, such as a hosted recipient at the owner's address.
  destination_tag	Option<u32>	An arbitrary tag to further specify the destination for this held payment, such as a hosted recipient at the destination address.
  destination_node	Option<&str>	A hint indicating which page of the destination's owner directory links to this object, in case the directory consists of multiple pages.

  Sources:

  • https://xrpl.org/escrow-object.html

• FeeSettings

  1. The FeeSettings object type contains the current base transaction cost and reserve amounts as determined by fee voting.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::FeeSettings	An indicator of what type of object it is.
  base_fee	&str	The transaction cost of the "reference transaction" in drops of XRP as hexadecimal.
  reference_fee_units	u32	The BaseFee translated into "fee units".
  reserve_base	u32	The base reserve for an account in the XRP Ledger, as drops of XRP.
  reserve_increment	u32	The incremental owner reserve for owning objects, as drops of XRP.
  flags	u32	A bit-map of boolean flags for this object. No flags are defined for this type.

  Sources:

  • https://xrpl.org/feesettings.html

• LedgerHashes

  1. The LedgerHashes object type contains a history of prior ledgers that led up to this ledger version, in the form of their hashes.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::LedgerHashes	An indicator of what type of object it is.
  first_ledger_sequence	u32	The "recent hashes" object of the production XRP Ledger has the value 2 in this field as a result of a previous rippled software. DEPRECATED
  last_ledger_sequence	u32	The Ledger Index of the last entry in this object's Hashes array.
  hashes	Vec<&str>	An array of up to 256 ledger hashes. The contents depend on which sub-type of LedgerHashes object this is.
  flags	u32	A bit-map of boolean flags for this object. No flags are defined for this type.

  Sources:

  • https://xrpl.org/ledgerhashes.html

• NegativeUNL

  1. The NegativeUNL object type contains the current status of the Negative UNL, a list of trusted validators currently believed to be offline.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::NegativeUNL	An indicator of what type of object it is.
  disabled_validators	Optional<DisabledValidator>	A list of DisabledValidator objects, each representing a trusted validator that is currently disabled.
  validator_to_disable	Option<&str>	The public key of a trusted validator that is scheduled to be disabled in the next flag ledger.
  validator_to_re_enable	Option<&str>	The public key of a trusted validator in the Negative UNL that is scheduled to be re-enabled in the next flag ledger.

  Sources:

  • https://xrpl.org/negativeunl.html

  • DisabledValidator

    1. Represents a trusted validator that is currently disabled.

    3. It could be represented as follows:

       #[derive(Debug, Serialize, Deserialize)]
       #[serde(rename_all(serialize = "PascalCase", deserialize = "snake_case"))]
       pub enum DisabledValidatorWrapper<'a> {
           DisabledValidator {
               first_ledger_sequence: u32,
               public_key: &'a str,
           }
       }

    fields	type	explanation
    first_ledger_sequence	u32
    public_key	&str

    Sources:

    • https://xrpl.org/negativeunl.html

• NFTokenOffer

  1. The NFTokenOffer object represents an offer to buy, sell or transfer an NFToken object.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::NFTokenOffer	An indicator of what type of object it is.
  owner	&str	Owner of the account that is creating and owns the offer.
  previous_txn_id	&str	Identifying hash of the transaction that most recently modified this object.
  previous_txn_lgr_seq	u32	Index of the ledger that contains the transaction that most recently modified this object
  token_id	&str	TokenID of the NFToken object referenced by this offer.
  amount	Currency	Amount expected or offered for the NFToken.
  expiration	u32	The time after which the offer is no longer active.
  destination	&str	The AccountID for which this offer is intended. If present, only that account can accept the offer.
  owner_node	&str	Internal bookkeeping, indicating the page inside the owner directory where this token is being tracked.
  offer_node	&str	Internal bookkeeping, indicating the page inside the token buy or sell offer directory, as appropriate, where this token is being tracked.
  flags	u32	A set of flags associated with this object, used to specify various options or settings.

  Sources:

  • https://xrpl.org/nftokenoffer.html

• NFTokenPage

  1. The NFTokenPage object represents a collection of NFToken objects owned by the same account.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::NFTokenPage	An indicator of what type of object it is.
  previous_page_min	&str	The locator of the previous page, if any.
  next_page_min	&str	The locator of the next page, if any.
  previous_txn_id	&str	Identifies the transaction ID of the transaction that most recently modified this NFTokenPage object.
  previous_txn_lgr_seq	u32	The sequence of the ledger that contains the transaction that most recently modified this NFTokenPage object.
  non_fungible_tokens	Vec<NFToken>	The collection of NFToken objects contained in this NFTokenPage object.

  Sources:

  • https://xrpl.org/nftokenpage.html

• Offer

  1. The Offer object type describes an offer to exchange currencies, more traditionally known as an order, in the XRP Ledger's distributed exchange.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::Offer	An indicator of what type of object it is.
  account	&str	The address of the account that owns this offer.
  flags	u32	A bit-map of boolean flags enabled for this offer.
  sequence	u32	The Sequence value of the OfferCreate transaction that created this Offer object.
  taker_pays	Currency	The remaining amount and type of currency requested by the offer creator.
  taker_gets	Currency	The remaining amount and type of currency being provided by the offer creator.
  book_directory	&str	The ID of the Offer Directory that links to this offer.
  book_node	&str	A hint indicating which page of the offer directory links to this object, in case the directory consists of multiple pages.
  owner_node	&str	A hint indicating which page of the owner directory links to this object, in case the directory consists of multiple pages.
  previous_txn_id	&str	The identifying hash of the transaction that most recently modified this object.
  previous_txn_lgr_seq	u32	The index of the ledger that contains the transaction that most recently modified this object.
  expiration	Option<u32>	Indicates the time after which this offer is considered unfunded.

  Sources:

  • https://xrpl.org/offer.html

• PayChannel

  1. The PayChannel object type represents a payment channel.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::PayChannel	An indicator of what type of object it is.
  account	&str	The source address that owns this payment channel.
  destination	&str	The destination address for this payment channel.
  amount	Currency::Xrp	Total XRP, in drops, that has been allocated to this channel.
  balance	Currency::Xrp	Total XRP, in drops, already paid out by the channel.
  public_key	&str	Public key, in hexadecimal, of the key pair that can be used to sign claims against this channel.
  settle_delay	u32	Number of seconds the source address must wait to close the channel if it still has any XRP in it.
  owner_node	&str	A hint indicating which page of the source address's owner directory links to this object, in case the directory consists of multiple pages.
  previous_txn_id	&str	The identifying hash of the transaction that most recently modified this object.
  previous_txn_lgr_seq	u32	The index of the ledger that contains the transaction that most recently modified this object.
  flags	u32	A bit-map of boolean flags enabled for this payment channel.
  expiration	Option<u32>	The mutable expiration time for this payment channel, in seconds since the Ripple Epoch.
  cancel_after	Option<u32>	The immutable expiration time for this payment channel, in seconds since the Ripple Epoch.
  source_tag	Option<u32>	An arbitrary tag to further specify the source for this payment channel, such as a hosted recipient at the owner's address.
  destination_tag	Option<u32>	An arbitrary tag to further specify the destination for this payment channel, such as a hosted recipient at the destination address.
  destination_node	Option<&str	A hint indicating which page of the destination's owner directory links to this object, in case the directory consists of multiple pages.

  Sources:

  • https://xrpl.org/paychannel.html

• RippleState

  1. The RippleState object type connects two accounts in a single currency.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::RippleState	An indicator of what type of object it is.
  flags	u32	A bit-map of boolean options enabled for this object.
  balance	Currency::IssuedCurrency	The balance of the trust line, from the perspective of the low account.
  low_limit	Currency::IssuedCurrency	The limit that the low account has set on the trust line.
  high_limit	Currency::IssuedCurrency	The limit that the high account has set on the trust line.
  previous_txn_id	&str	The identifying hash of the transaction that most recently modified this object.
  previous_txn_lgr_seq	u32	The index of the ledger that contains the transaction that most recently modified this object.
  low_node	Option<&str>	A hint indicating which page of the low account's owner directory links to this object, in case the directory consists of multiple pages.
  high_node	Option<&str>	A hint indicating which page of the high account's owner directory links to this object, in case the directory consists of multiple pages.
  low_quality_in	Option<u32>	The inbound quality set by the low account, as an integer in the implied ratio LowQualityIn:1,000,000,000.
  low_quality_out	Option<u32>	The outbound quality set by the low account, as an integer in the implied ratio LowQualityOut:1,000,000,000.
  high_quality_in	Option<u32>	The inbound quality set by the high account, as an integer in the implied ratio HighQualityIn:1,000,000,000.
  high_quality_out	Option<u32>	The outbound quality set by the high account, as an integer in the implied ratio HighQualityOut:1,000,000,000.

  Sources:

  • https://xrpl.org/ripplestate.html

• SignerList

  1. The SignerList object type represents a list of parties that, as a group, are authorized to sign a transaction in place of an individual account.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::SignerList	An indicator of what type of object it is.
  flags	u32	A bit-map of Boolean flags enabled for this signer list.
  previous_txn_id	&str	The identifying hash of the transaction that most recently modified this object.
  previous_txn_lgr_seq	u32	The index of the ledger that contains the transaction that most recently modified this object.
  owner_node	&str	A hint indicating which page of the owner directory links to this object, in case the directory consists of multiple pages.
  signer_entries	Vec<SignerEntry>	An array of Signer Entry objects representing the parties who are part of this signer list.
  signer_list_id	u32	An ID for this signer list. Currently always set to 0.
  signer_quorum	u32	A target number for signer weights. To produce a valid signature for the owner of this SignerList, the signers must provide valid signatures whose weights sum to this value or more.

  Sources:

  • https://xrpl.org/signerlist.html

  • SignerEntry
    1.

    2.
    
    3.
    
    | fields | type | explanation |
    | --- | --- | --- |
    | `account` | `&str` | An XRP Ledger address whose signature contributes to the multi-signature. |
    | `signer_weight` | `u32` | The weight of a signature from this signer. |
    | `wallet_locator` | `Option<&str>` | This can be used to identify the signer or for other, related purposes. |
    
    Sources:
      - https://xrpl.org/signerlist.html
    

• Ticket

  1. The Ticket object type represents a Ticket, which tracks an account sequence number that has been set aside for future use.

  fields	type	explanation
  ledger_entry_type	LedgerEntryType::Ticket	An indicator of what type of object it is.
  account	&str	The account that owns this Ticket.
  flags	u32	A bit-map of Boolean flags enabled for this Ticket.
  owner_node	&str	A hint indicating which page of the owner directory links to this object, in case the directory consists of multiple pages.
  previous_txn_id	&str	The identifying hash of the transaction that most recently modified this object.
  previous_txn_lgr_seq	u32	The index of the ledger that contains the transaction that most recently modified this object.
  ticket_sequence	u32	The Sequence Number this Ticket sets aside.

  Sources:

  • https://xrpl.org/ticket.html

We should have an own directory for the requests and put the types in separate files. This really improves the library’s structure.

Needs to be further defined.

Considering that the NFToken amendment is becoming more and more likely to get approved, we should prepare this library to support all things related to the amendment. The NFToken transactions are already merged into the develop branch but the requests are missing.

• account_nfts
• nftoken_buy_offers
• nftoken_sell_offers

Rollback dev branch to commit 095f5c4 as my last commits weren't verified.

Research still needs to be done.

Documentation:

• https://xrpl-hooks.readme.io/

We should have an integration test workflow that set's up a rippled node in stand-alone mode using natenichols/rippled-standalone. That way we can test if our models, like transactions get submitted properly.

References:

• https://github.com/natenichols/rippled-standalone
• https://github.com/XRPLF/xrpl-py/blob/master/.github/workflows/integration_test.yml
• https://github.com/XRPLF/xrpl.js/blob/main/.github/workflows/nodejs.yml
• https://github.com/sologenic/ripple-lib/blob/main/.github/workflows/nodejs.yml

We will have different functions to convert offers quality and transfer rate.

• percent_to_transfer_rate
• decimal_to_transfer_rate
• transfer_rate_to_decimal
• decimal_to_quality
• quality_to_decimal
• percent_to_quality

Sources:

• https://github.com/XRPLF/xrpl.js/blob/main/packages/xrpl/src/utils/quality.ts

• maker_to_taker_quality
• taker_to_maker_quality

There are some improvements need to be done to the current models for transactions and requests:

• utilize Default, PartialEq, Eq, Clone traits
• split up Currency into Currency and Amount
  • Currency::Xrp must have fiel name currency
• add tests for serializing and deserializing models
  • add macro to serialize and deserialize a struct with its tag (e.g. {"StructName": {"foo": 0, "bar": 1}})
• change impl lifetimes
• cleanup models/mod.rs (e.g StreamParameter should be in requests/subscribe.rs)
• add non-common-fields documentation
• look over request_fields.rs and move to models/requests
• Add signing request methods with feature flag
• Add ˋnewˋ methods to all models
  • change tests to use new

Clients:

WebsocketClient

std

Crates

• embedded-websocket
• tokio
• tokio-rustls

DNS

The tokio crate provides dns lookup functionalities.

TLS

The crate tokio-rustls can be used to establish secure connections.

Networking

The crate embedded-websocket provides all functionalities for opening a websocket connection and sending/receiving messages through that connection. It takes a TcpStream to establish a connection.

no_std

Crates

• embedded-websocket
• embassy-net
• embassy-net-driver
• embedded-tls

DNS

TLS

The crate embedded-tls to establish secure connections.

Networking

JsonRpcClient

std

Crates

• reqwless
• tokio
• tokio-rustls

DNS

The tokio crate provides dns lookup functionalities we're using when the std feature is enabled.

TLS

The crate tokio-rustls can be used to establish secure connections.

Networking

The crate reqwless is used for HttpClient to send JsonRpc requests. It takes a TcpStream to establish a connection.

no_std

Crates

• reqwless
• embassy-net
• embassy-net-driver
• embedded-tls

DNS

TLS

Networking

The crate reqwless is used for HttpClient to send JsonRpc requests. It takes a TcpStream to establish a connection.

Features

• dns
• tls

Traits

Client

_request_impl

An asynchronous driver for a given request.

AsyncClient

request

An asynchronous method which by default simply awaits the Client._request_impl method.

WebsocketBase

is_open

Checks if the websocket client is open.

_set_up_future

This method is to ensure that a request with an ID is backed by an open future.

_handler

An asynchronous method to resolve any outstanding futures for all messages we are receiving and push it to the message queue.

_do_open

An asynchronous method to connect to the host. It also sets the message queue and polls the _handler task.

_do_close

An asynchronous method to close the connection between the client and the host. It cancels the _handler task and any open request futures. We also clear the message queue here and finally close the connection.

_do_send

An asynchronous method which creates a future for the given request and then sends the request.

_do_request_impl

An asynchronous method that injects an ID into a request if the user haven't provided one. It then sends the request and waits for the future to be resolved to return the response.

Needs to be further defined

Potential segfault in localtime_r invocations

Impact

Unix-like operating systems may segfault due to dereferencing a dangling pointer in specific circumstances. This requires an environment variable to be set in a different thread than the affected functions. This may occur without the user's knowledge, notably in a third-party library.

Workarounds

No workarounds are known.

References

• time-rs/time#293

See advisory page for additional details.

• 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.

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.

• 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.

• 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.

• 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.

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.

Sources:

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

1. A model that represents a clients response.

Methods

• contains_partial_payment
• is_successful

Account methods

AccountChannelsResponse

Channel

Sources:

• https://github.com/XRPLF/xrpl-py/blob/master/xrpl/models/response.py#L37

• Errors have a resource field that needs to be defined.

Utilize modern error handling:

thiserror:
https://docs.rs/thiserror/latest/thiserror/
https://crates.io/crates/thiserror/1.0.24

anyhow:
https://docs.rs/anyhow/latest/anyhow/
https://crates.io/crates/anyhow

This has to be implemented for existing errors and has to be done for all future errors

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 #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 #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.

This is supposed to be an ongoing task. A collection of nits. Maybe just look into this task before pushing to development branch. Simply remove key point as soon as fixed.

• https://github.com/sephynox/xrpl-rust/blob/develop/src/core/addresscodec/mod.rs#L104 should be "Returns a decoded seed."
• https://github.com/sephynox/xrpl-rust/blob/develop/src/core/addresscodec/mod.rs#L477 should be "Returns the decoded bytes of the account public key."

CAUTION: At the time of writing there are multiple mistakes in the XRPL-Dev-Portal, regarding XLS-20. Please also consider this issue.

Transactions:

• NFTokenAcceptOffer
• NFTokenBurn
• NFTokenCreateOffer
• NFTokenCancelOffer
• NFTokenMint

Requests:

• NFTokenBuyOffers
• NFTokenSellOffers

Although the current type of the marker field (str) is more flexible which would make sense because the Marker has no fixed format, most nodes (including https://xrpl.org/public-servers.html#public-servers) define it as u32. When defining it as string and requesting, the node sends an error (invalidParams).

• 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.

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.

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.

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.

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.

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 #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.

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 #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
}

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.

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.

Sources:

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

• 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.

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

We should have a base trait that adds some basic functionalities (ˋfrom_xrplˋ, ˋto_xrplˋ, ˋto_jsonˋ, ˋto_hash_mapˋ, ˋvalidateˋ, etc.), every structure should have. We could use https://github.com/XRPLF/xrpl-py/blob/521988cf09be6979ffecab4d6b1bf37be41df970/xrpl/models/base_model.py#L66 as a reference.

• 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.

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".

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".

Sources:

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

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:

    • ...

• get_balance_changes

  1. A utility function to parse the balance changes for each account affected by a transaction.

  fields	type	explanation
  metadata	Metadata	A model to represent a transactions metadata.

  Sources:

  • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/utils/txn_parser/get_balance_changes.py#L15

• get_final_balances

  1. A utility function to parse the final balances for each account affected by a transaction.

  fields	type	explanation
  metadata	Metadata	A model to represent a transactions metadata.

  Sources:

  • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/utils/txn_parser/get_final_balances.py#L15

• get_order_book_changes

  1. A utility function to parse the order book changes caused by a transaction.

  fields	type	explanation
  metadata	Metadata	A model to represent a transactions metadata.

  Sources:

  • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/utils/txn_parser/get_order_book_changes.py#L9

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:

    • ...

• create_cross_chain_payment -> Payment

  1. A utility function to create a cross chain payment.

  fields	type	explanation
  payment	Payment	A Payment transaction model.
  destination	&str	The destination account on the sidechain

  Sources:

  • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/utils/sidechain.py#L8
  • https://xrpl.org/federated-sidechains.html#federated-sidechains

Currently all struct fields for transaction and request models are serialized from sake_case to PascalCase. This is a problem because fields like flags for transactions and account for requests both need to be lowercase, but when serializing they get renamed to Flags and Account, which is invalid. I tried using #[serde(rename = "flags")], but #[serde(rename_all(serialize = "PascalCase", deserialize = "snake_case"))] seems to have a higher priority. It is possible to build custom Serialize implementations, but I could not figure out a good way to do it, yet.

Many ˋnewˋ methods of the models are private. #67 fixes that.

A directory where people can add snippets. It is a place to add code that do not really fit to a library, but could be helpful to people.
This issue is only about adding that directory.

Examples:

• function to safely delete an account

Walkthroughs:

• https://github.com/XRPLF/xrpl.js/blob/main/packages/xrpl/snippets/src/sendEscrow.ts

Implement the Default for any struct it makes sense. The following example shows how much it makes it easier to define a struct:

let request = AccountInfo {
    account: "r3rhWeE31Jt5sWmi4QiGLMZnY3ENgqw96W",
    ..Default::default()
};

Instead of having to define all fields for AccountInfo the user can just define the account and leave the rest to ..Default::default().

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:

    • ...

• str_to_hex -> &str

  1. A function to convert a UTF-8-encoded string into hexadecimal encoding.

  fields	type	explanation
  string	&str	A UTF-8-encoded string.

  Sources:

  • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/utils/str_conversions.py#L4

• hex_to_str -> &str

  1. A function to convert a hex string into a human-readable string.

  fields	type	explanation
  hex_string	&str	A hex string.

  Sources:

  • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/utils/str_conversions.py#L19

https://docs.rs/crypto-bigint/latest/crypto_bigint/

• Refactor the transaction and request models to match the order of fields introduced by #58
• Utilize Cow for &str types

Replace the deprecated ripdemd160 crate with the ripemd crate.

Deprecated: https://crates.io/crates/ripemd160
Replacement: https://crates.io/crates/ripemd

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:

    • ...

• generate_faucet_wallet

  1. A function to generate a new Wallet and funds it using the XRPL Testnet Faucet.

  2. Uses Wallet::create to create a new Wallet and uses a request_funding function to fund that wallet.

  fields	type	explanation
  client	WebsocketClient/AsyncWebsocketClient	A websocket client object.
  wallet	Option<Wallet>	A wallet object to fund.
  faucet_host	&str	A custom host to use for funding a wallet.

  Sources:

  • https://github.com/XRPLF/xrpl-py/blob/master/xrpl/asyncio/wallet/wallet_generation.py#L26

Needs to be defined.

The transactions currently implement the From trait in a very weird way to convert the flags. It doesn't really make sense. The From trait should be implemented for the ...Flag enum.

Generally an id for requests can be typed as u32 or as str. Currently they are typed as u32. IMO we should type it as str. It would be more flexible. You could give the request an id that's really describing what it does while still being able to set it "1".

I find it easier to work with currencies and currency amounts if they were unique structs. So you would have the following structs:
Currencies:

• IssuedCurrency
• XRP

Amounts:

• IssuedCurrencyAmount
• XRPAmount

Currently I am having issues accessing the Currency amount but maybe you know a way how to write a get_amount_value function. The way I am suggesting is how other libraries do it (except for the XRPAmount). You can then wrap the currencies in a Currency enum and the amounts in a Amount enum.

• AccountChannelsResponse

  fields	type	explanation
  account	&str	The owner's account's address
  channels	Vec<PayChannel>	The channels owned by the account
  ledger_index	u36	The index of the ledger that was used to generate this response
  ledger_hash	Option<&str>	The hash of the ledger that was used to generate this response
  validated	Option<bool>	Wether the ledger that was used to generate this response was validated
  limit	Option<u32>	The max limit of how many channels to return
  marker	Option<Maker>	Server-defined value for pagination.

• AccountCurrenciesResponse

  fields	type	explanation
  account	&str	The account's address
  ledger_index	u32	The index of the ledger that was used to generate this response
  receive_currencies	Vec<&str>	The currencies the account can receive
  send_currencies	Vec<&str>	The currencies the account can send
  validated	bool	Wether the ledger that was used to generate this response was validated
  ledger_hash	Option<&str>	The hash of the ledger that was used to generate this response

• AccountInfoResponse

  fields	type	explanation
  account_data	AccountRoot	The AccountRoot ledger object with this account's information, as stored in the ledger.
  signer_lists	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• AccountLinesResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• AccountNftsResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• AccountObjectsResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• AccountOffersResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• AccountTxResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• GatewayBalancesResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• NorippleCheckResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• LedgerResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• LedgerClosedResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• LedgerCurrentResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• LedgerDataResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• LedgerEntryResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• SubmitResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• SubmitMultisignedResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• TransactionEntryResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• TxResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• TxHistoryResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• BookOffersResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• DepositAuthorizedResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• NftBuyOffersResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• NftSellOffersResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• PathFindResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• RipplePathFindResponse

  fields	type	explanation
  ``	``

• ChannelAuthorizeResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• ChannelVerifyResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• SubscribeResponse
  SubscribeResponse should be an enum containing the different stream response types.

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• UnsubscribeResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• FeeResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• ManifestResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• ServerInfoResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  fields	type	explanation
  ---	---	---
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• ClioServerInfoResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• ClioLedgerResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• ClioNftInfoResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• JsonResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• PingResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``

• RandomResponse

  fields	type	explanation
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``
  ``	``