feat: add submit and wait for transaction submission

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [[Unreleased]]
+### Added:
+- Added `submit_and_wait` to sign (if needed), autofill, submit a transaction and wait for its final outcome
+- `submit` and `send_reliable_submission` now accept an optional boolean param `fail_hard` (if `True` halt the submission if it's not immediately validated)
+
 ### Fixed:
 - Refactored `does_account_exist` and `get_balance` to avoid deprecated methods and use `ledger_index` parameter
 

snippets/multisign.py

@@ -1,14 +1,7 @@
 """Example of how we can multisign a transaction"""
 from xrpl.clients import JsonRpcClient
-from xrpl.models.requests import SubmitMultisigned
 from xrpl.models.transactions import AccountSet, SignerEntry, SignerListSet
-from xrpl.transaction import (
-    autofill,
-    autofill_and_sign,
-    multisign,
-    send_reliable_submission,
-    sign,
-)
+from xrpl.transaction import autofill, multisign, sign, submit_and_wait
 from xrpl.utils import str_to_hex
 from xrpl.wallet import generate_faucet_wallet
 
@@ -29,12 +22,12 @@
     signer_quorum=2,
     signer_entries=signer_entries,
 )
-signed_signer_list_set_tx = autofill_and_sign(signer_list_set_tx, master_wallet, client)
 
-print("Constructed SignerListSet and submitting it to the ledger...")
-signed_list_set_tx_response = send_reliable_submission(
-    signed_signer_list_set_tx, client
+print(
+    """Constructing SignerListSet then autofilling, signing,
+    and submitting it to the ledger..."""
 )
+signed_list_set_tx_response = submit_and_wait(signer_list_set_tx, client, master_wallet)
 print("SignerListSet submitted, here's the response:")
 print(signed_list_set_tx_response)
 
@@ -57,15 +50,17 @@
 print("Successfully multisigned the transaction")
 print(multisigned_tx)
 
-multisigned_tx_response = client.request(SubmitMultisigned(tx_json=multisigned_tx))
+multisigned_tx_response = submit_and_wait(multisigned_tx, client)
+
+print(multisigned_tx_response)
 
-if multisigned_tx_response.result["engine_result"] == "tesSUCCESS":
+if multisigned_tx_response.result["validated"]:
     print("The multisigned transaction was accepted by the ledger:")
     print(multisigned_tx_response)
-    if multisigned_tx_response.result["tx_json"]["Signers"]:
+    if multisigned_tx_response.result["Signers"]:
         print(
             "The transaction had "
-            f"{len(multisigned_tx_response.result['tx_json']['Signers'])} signatures"
+            f"{len(multisigned_tx_response.result['Signers'])} signatures"
         )
 else:
     print(

snippets/partial_payment.py

@@ -3,7 +3,7 @@
 from xrpl.models.amounts import IssuedCurrencyAmount
 from xrpl.models.requests import AccountLines
 from xrpl.models.transactions import Payment, PaymentFlag, TrustSet
-from xrpl.transaction import autofill_and_sign, send_reliable_submission
+from xrpl.transaction import submit_and_wait
 from xrpl.wallet import generate_faucet_wallet
 
 # References
@@ -30,8 +30,7 @@
 )
 
 # Sign and autofill, then send transaction to the ledger
-signed_trust_set_tx = autofill_and_sign(trust_set_tx, wallet2, client)
-send_reliable_submission(signed_trust_set_tx, client)
+submit_and_wait(trust_set_tx, client, wallet2)
 
 # Both balances should be zero since nothing has been sent yet
 print("Balances after trustline is claimed:")
@@ -51,8 +50,7 @@
 )
 
 # Sign and autofill, then send transaction to the ledger
-signed_payment_tx = autofill_and_sign(payment_tx, wallet1, client)
-payment_response = send_reliable_submission(signed_payment_tx, client)
+payment_response = submit_and_wait(payment_tx, client, wallet1)
 print(payment_response)
 
 # Issuer (wallet1) should have -3840 FOO and destination (wallet2) should have 3840 FOO
@@ -86,8 +84,7 @@
 )
 
 # Sign and autofill, then send transaction to the ledger
-signed_partial_payment_tx = autofill_and_sign(partial_payment_tx, wallet2, client)
-partial_payment_response = send_reliable_submission(signed_partial_payment_tx, client)
+partial_payment_response = submit_and_wait(partial_payment_tx, client, wallet2)
 print(partial_payment_response)
 
 # Tried sending 4000 of 3840 FOO -> wallet1 and wallet2 should have 0 FOO

snippets/reliable_transaction_submission.py

@@ -3,7 +3,7 @@
 from xrpl.clients import JsonRpcClient
 from xrpl.models.requests import Tx
 from xrpl.models.transactions import Payment
-from xrpl.transaction import autofill_and_sign, send_reliable_submission
+from xrpl.transaction import submit_and_wait
 from xrpl.wallet import generate_faucet_wallet
 
 # References:
@@ -30,11 +30,8 @@
     destination=wallet2.classic_address,
 )
 
-# Sign and autofill the transaction (prepares it to be ready to submit)
-signed_payment_tx = autofill_and_sign(payment_tx, wallet1, client)
-
-# Submits transaction and waits for response (validated or rejected)
-payment_response = send_reliable_submission(signed_payment_tx, client)
+# Signs, autofills, and submits transaction and waits for response (validated or rejected)
+payment_response = submit_and_wait(payment_tx, client, wallet1)
 print("Transaction was submitted")
 
 # Create a Transaction request to see transaction

snippets/send_escrow.py

@@ -5,7 +5,7 @@
 from xrpl.clients import JsonRpcClient
 from xrpl.models.requests import AccountObjects
 from xrpl.models.transactions import EscrowCreate, EscrowFinish
-from xrpl.transaction import autofill_and_sign, send_reliable_submission
+from xrpl.transaction.reliable_submission import submit_and_wait
 from xrpl.utils import datetime_to_ripple_time
 from xrpl.wallet import generate_faucet_wallet
 
@@ -37,8 +37,7 @@
     finish_after=finish_after,
 )
 
-signed_create_tx = autofill_and_sign(create_tx, wallet1, client)
-create_escrow_response = send_reliable_submission(signed_create_tx, client)
+create_escrow_response = submit_and_wait(create_tx, wallet1, client)
 print(create_escrow_response)
 
 # Create an AccountObjects request and have the client call it to see if escrow exists
@@ -55,8 +54,7 @@
     offer_sequence=create_escrow_response.result["Sequence"],
 )
 
-signed_finish_tx = autofill_and_sign(finish_tx, wallet1, client)
-send_reliable_submission(signed_finish_tx, client)
+submit_and_wait(finish_tx, client, wallet1)
 
 # If escrow went through successfully, 1000000 exchanged
 print("Balances of wallets after Escrow was sent:")

snippets/set_regular_key.py

@@ -2,7 +2,7 @@
 from xrpl.account import get_balance
 from xrpl.clients import JsonRpcClient
 from xrpl.models.transactions import Payment, SetRegularKey
-from xrpl.transaction import autofill_and_sign, send_reliable_submission
+from xrpl.transaction import submit_and_wait
 from xrpl.wallet import generate_faucet_wallet
 
 # References
@@ -28,8 +28,7 @@
     account=wallet1.classic_address, regular_key=regular_key_wallet.classic_address
 )
 
-signed_tx = autofill_and_sign(tx, wallet1, client)
-set_regular_key_response = send_reliable_submission(signed_tx, client)
+set_regular_key_response = submit_and_wait(tx, wallet1, client)
 
 print("Response for successful SetRegularKey tx:")
 print(set_regular_key_response)
@@ -42,8 +41,7 @@
     amount="1000",
 )
 
-signed_payment = autofill_and_sign(payment, regular_key_wallet, client)
-payment_response = send_reliable_submission(signed_payment, client)
+payment_response = submit_and_wait(payment, client, regular_key_wallet)
 
 print("Response for tx signed using Regular Key:")
 print(payment_response)

tests/integration/sugar/test_transaction.py

@@ -15,12 +15,14 @@
     autofill_and_sign,
     send_reliable_submission,
     sign,
+    submit_and_wait,
 )
 from xrpl.asyncio.transaction import (
     submit_transaction as submit_transaction_alias_async,
 )
 from xrpl.clients import XRPLRequestFailureException
 from xrpl.core.addresscodec import classic_address_to_xaddress
+from xrpl.core.binarycodec.main import encode
 from xrpl.models.exceptions import XRPLException
 from xrpl.models.requests import Tx
 from xrpl.models.transactions import AccountDelete, AccountSet, EscrowFinish, Payment
@@ -354,3 +356,122 @@ async def test_reliable_submission_no_last_ledger_sequence(self, client):
         signed_payment_transaction = await sign(payment_transaction, WALLET)
         with self.assertRaises(XRPLReliableSubmissionException):
             await send_reliable_submission(signed_payment_transaction, client)
+
+
+class TestSubmitAndWait(IntegrationTestCase):
+    @test_async_and_sync(
+        globals(),
+        [
+            "xrpl.transaction.submit_and_wait",
+            "xrpl.account.get_next_valid_seq_number",
+            "xrpl.ledger.get_fee",
+        ],
+    )
+    async def test_submit_and_wait_simple(self, client):
+        account_set = AccountSet(
+            account=ACCOUNT,
+            set_flag=SET_FLAG,
+        )
+        await accept_ledger_async(delay=1)
+        response = await submit_and_wait(account_set, client, WALLET)
+        self.assertTrue(response.result["validated"])
+        self.assertEqual(response.result["meta"]["TransactionResult"], "tesSUCCESS")
+        self.assertTrue(response.is_successful())
+        self.assertEqual(response.result["Fee"], await get_fee(client))
+        WALLET.sequence += 1
+
+    @test_async_and_sync(
+        globals(),
+        [
+            "xrpl.transaction.submit_and_wait",
+            "xrpl.account.get_next_valid_seq_number",
+            "xrpl.ledger.get_fee",
+        ],
+    )
+    async def test_submit_and_wait_payment(self, client):
+        payment_transaction = Payment(
+            account=ACCOUNT,
+            amount="10",
+            destination=DESTINATION,
+        )
+        await accept_ledger_async(delay=1)
+        response = await submit_and_wait(payment_transaction, client, WALLET)
+        self.assertTrue(response.result["validated"])
+        self.assertEqual(response.result["meta"]["TransactionResult"], "tesSUCCESS")
+        self.assertTrue(response.is_successful())
+        self.assertEqual(response.result["Fee"], await get_fee(client))
+        WALLET.sequence += 1
+
+    @test_async_and_sync(
+        globals(),
+        [
+            "xrpl.transaction.autofill_and_sign",
+            "xrpl.transaction.submit_and_wait",
+            "xrpl.account.get_next_valid_seq_number",
+            "xrpl.ledger.get_fee",
+        ],
+    )
+    async def test_submit_and_wait_signed(self, client):
+        payment_transaction = Payment(
+            account=ACCOUNT,
+            amount="10",
+            destination=DESTINATION,
+        )
+        payment_transaction_signed = await autofill_and_sign(
+            payment_transaction, WALLET, client
+        )
+        await accept_ledger_async(delay=1)
+        response = await submit_and_wait(payment_transaction_signed, client)
+        self.assertTrue(response.result["validated"])
+        self.assertEqual(response.result["meta"]["TransactionResult"], "tesSUCCESS")
+        self.assertTrue(response.is_successful())
+        self.assertEqual(response.result["Fee"], await get_fee(client))
+        WALLET.sequence += 1
+
+    @test_async_and_sync(
+        globals(),
+        [
+            "xrpl.transaction.autofill_and_sign",
+            "xrpl.transaction.submit_and_wait",
+            "xrpl.account.get_next_valid_seq_number",
+            "xrpl.ledger.get_fee",
+            "xrpl.core.binarycodec.main.encode",
+        ],
+    )
+    async def test_submit_and_wait_blob(self, client):
+        payment_transaction = Payment(
+            account=ACCOUNT,
+            amount="10",
+            destination=DESTINATION,
+        )
+        payment_transaction_signed = await autofill_and_sign(
+            payment_transaction, WALLET, client
+        )
+        await accept_ledger_async(delay=1)
+        payment_transaction_signed_blob = encode(payment_transaction_signed.to_xrpl())
+        response = await submit_and_wait(payment_transaction_signed_blob, client)
+        self.assertTrue(response.result["validated"])
+        self.assertEqual(response.result["meta"]["TransactionResult"], "tesSUCCESS")
+        self.assertTrue(response.is_successful())
+        self.assertEqual(response.result["Fee"], await get_fee(client))
+        WALLET.sequence += 1
+
+    @test_async_and_sync(
+        globals(),
+        [
+            "xrpl.transaction.submit_and_wait",
+            "xrpl.account.get_next_valid_seq_number",
+            "xrpl.ledger.get_latest_validated_ledger_sequence",
+        ],
+    )
+    async def test_submit_and_wait_last_ledger_expiration(self, client):
+        payment_transaction = Payment(
+            account=ACCOUNT,
+            last_ledger_sequence=await get_latest_validated_ledger_sequence(client),
+            fee="10",
+            amount="100",
+            destination=DESTINATION,
+        )
+        await accept_ledger_async(delay=1)
+        with self.assertRaises(XRPLReliableSubmissionException):
+            await submit_and_wait(payment_transaction, client, WALLET)

xrpl/asyncio/transaction/__init__.py

@@ -15,6 +15,7 @@
 from xrpl.asyncio.transaction.reliable_submission import (
     XRPLReliableSubmissionException,
     send_reliable_submission,
+    submit_and_wait,
 )
 
 __all__ = [
@@ -27,6 +28,7 @@
     "sign",
     "sign_and_submit",
     "submit",
+    "submit_and_wait",
     "submit_transaction",
     "transaction_json_to_binary_codec_form",
     "send_reliable_submission",

xrpl/asyncio/transaction/main.py

@@ -147,13 +147,18 @@ async def autofill_and_sign(
 async def submit(
     transaction: Transaction,
     client: Client,
+    *,
+    fail_hard: bool = False,
 ) -> Response:
     """
     Submits a transaction to the ledger.
 
     Args:
         transaction: the Transaction to be submitted.
         client: the network client with which to submit the transaction.
+        fail_hard: an optional boolean. If True, and the transaction fails for
+            the initial server, do not retry or relay the transaction to other
+            servers. Defaults to False.
 
     Returns:
         The response from the ledger.
@@ -162,7 +167,9 @@ async def submit(
         XRPLRequestFailureException: if the rippled API call fails.
     """
     transaction_blob = encode(transaction.to_xrpl())
-    response = await client._request_impl(SubmitOnly(tx_blob=transaction_blob))
+    response = await client._request_impl(
+        SubmitOnly(tx_blob=transaction_blob, fail_hard=fail_hard)
+    )
     if response.is_successful():
         return response