xrpl-dev-portal
xrpl-dev-portal copied to clipboard
Update Reliable Transaction Submission docs
There are various approaches or levels of "reliably" sending a transaction.
At a basic level, you submit a transaction, then wait until the tx
command gives a validated response or the transaction has expired. The xrpl.js 2.0 and xrpl-py client libraries have built in methods for this "submit and wait" style of not-disaster-resistant transaction submission. (xrpl4j currently does not.) The Reliable Transaction Submission guide should be updated to reflect the existence of those methods and to clarify the difference between levels or degrees of "reliable" submission.
There's also an asynchronous way of doing this, where you submit the transaction, carry on doing other stuff, and eventually circle back to confirm the transaction's validated outcome.
Sometimes you want to send and follow up asynchronously, but sometimes you really need to wait until it a transaction is done before moving on, and I don't know if it's possible to know which situation is more common. Ultimately we probably have to introduce people to the idea of both approaches (and beyond¹).
For most tutorials, we generally use a "submit and wait" type function where available. Unfortunately that's a little messy because some of the libraries (xrpl4j right now) don't have one so they need a different number of steps and overall flow than libraries that have one.
We may also want to add separate docs and examples for how to do the asynchronous version, which can include various optimizations like subscribing to the transactions stream, using tx's min_ledger
and max_ledger
parameters to ensure that the server has the necessary history, and so on.
¹The Beyond
Truly "reliable" transaction submission is arguably a neverending fight against everything that could possibly go wrong. You could have a disaster-recovery system that persists a transaction before submitting it redundantly to multiple servers, meticulously double-checks the network state against its own local records, automatically rebuilds a known state after a network or power outage, automatically adjusts to compensate for various types of failures to ensure that some version of the transaction ultimately succeeds if at all possible, etc. etc.
Being able to recover from a crash or power outage usually means having persistent storage like a database or message queue, which is not something that can/should be built directly into a library. It becomes more of a service because of the infrastructure involved. Businesses that handle deposits and withdrawals—like custodial exchanges or stablecoin issuers—probably need to have this type of system to make sure stuff like all withdrawals happen exactly once.
Re-creating a transaction after it failed is particularly challenging because if you're ever wrong that it failed, you can end up paying twice for something. Plus, some types of failure require you to change different things about the transaction, which can get very specific to individual cases.
It might help to update the Reliable Transaction Submission doc with this information, or come up with snappy names for different levels, or add a table showing the capabilities and needs of different methods/approaches.
#1197 now updates the Send XRP tutorial to use the reliable send functions (TBD: renaming the xrpl.js 2.0 one) but the rest of this ticket is still to-do.