Refactor Send XRP: reliable sub, folders by language

- Use reliable transaction submission methods where available
- Update text to describe the functions (esp. xrpl.js 2.0 stuff)
- Move Send XRP code samples to subfolders by language for consistency
  with other tutorials

content/_code-samples/send-xrp/js/send-xrp.js

@@ -0,0 +1,53 @@
+// Dependencies for Node.js.
+// In browsers, use a <script> tag instead.
+if (typeof module !== "undefined") {
+  // gotta use var here because const/let are block-scoped to the if statement.
+  var xrpl = require('xrpl')
+}
+
+// Example credentials
+const wallet = xrpl.Wallet.fromSeed("sn3nxiW7v8KXzPzAqzyHXbSSKNuN9")
+
+// Connect -------------------------------------------------------------------
+async function main() {
+  console.log("Connecting to Testnet...")
+  const api = new xrpl.Client('wss://s.altnet.rippletest.net:51233')
+  await api.connect()
+
+  // Get credentials from the Testnet Faucet -----------------------------------
+  console.log("Getting a wallet from the Testnet faucet...")
+  const {wallet, balance} = await api.fundWallet()
+
+  // Prepare transaction -------------------------------------------------------
+  const prepared = await api.autofill({
+    "TransactionType": "Payment",
+    "Account": wallet.address,
+    "Amount": xrpl.xrpToDrops("22"),
+    "Destination": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe"
+  })
+  const max_ledger = prepared.LastLedgerSequence
+  console.log("Prepared transaction instructions:", prepared)
+  console.log("Transaction cost:", xrpl.dropsToXrp(prepared.Fee), "XRP")
+  console.log("Transaction expires after ledger:", max_ledger)
+
+  // Sign prepared instructions ------------------------------------------------
+  const signed = wallet.sign(prepared)
+  console.log("Identifying hash:", signed.hash)
+  console.log("Signed blob:", signed.tx_blob)
+
+  // Submit signed blob --------------------------------------------------------
+  const tx = await api.submitSignedReliable(signed.tx_blob)
+  // This raises an exception if the transaction isn't confirmed.
+
+  // Wait for validation -------------------------------------------------------
+  // submitSignedReliable() handles this automatically, but it can take 4-7s.
+
+  // Check transaction results -------------------------------------------------
+  console.log("Transaction result:", tx.result.meta.TransactionResult)
+  console.log("Balance changes:", JSON.stringify(xrpl.getBalanceChanges(tx.result.meta), null, 2))
+
+  // End of main()
+  api.disconnect()
+}
+
+main()

content/_code-samples/send-xrp/py/send-xrp.py

@@ -34,35 +34,13 @@ print("Transaction expires after ledger:", max_ledger)
 print("Identifying hash:", tx_id)
 
 # Submit transaction -----------------------------------------------------------
-validated_index = xrpl.ledger.get_latest_validated_ledger_sequence(client)
-min_ledger = validated_index + 1
-print(f"Can be validated in ledger range: {min_ledger} - {max_ledger}")
-
-# Tip: you can use xrpl.transaction.send_reliable_submission(signed_tx, client)
-#  to send the transaction and wait for the results to be validated.
 try:
-    prelim_result = xrpl.transaction.submit_transaction(signed_tx, client)
-except xrpl.clients.XRPLRequestFailureException as e:
+    tx_response = xrpl.transaction.send_reliable_submission(signed_tx, client)
+except xrpl.transaction.XRPLReliableSubmissionException as e:
     exit(f"Submit failed: {e}")
-print("Preliminary transaction result:", prelim_result)
 
 # Wait for validation ----------------------------------------------------------
-# Note: If you used xrpl.transaction.send_reliable_submission, you can skip this
-#  and use the result of that method directly.
-from time import sleep
-while True:
-    sleep(1)
-    validated_ledger = xrpl.ledger.get_latest_validated_ledger_sequence(client)
-    tx_response = xrpl.transaction.get_transaction_from_hash(tx_id, client)
-    if tx_response.is_successful():
-        if tx_response.result.get("validated"):
-            print("Got validated result!")
-            break
-        else:
-            print(f"Results not yet validated... "
-                  f"({validated_ledger}/{max_ledger})")
-    if validated_ledger > max_ledger:
-        print("max_ledger has passed. Last tx response:", tx_response)
+# send_reliable_submission() handles this automatically, but it can take 4-7s.
 
 # Check transaction results ----------------------------------------------------
 import json

content/_code-samples/send-xrp/send-xrp.js

@@ -1,87 +0,0 @@
-// Example credentials
-const wallet = xrpl.Wallet.fromSeed("sn3nxiW7v8KXzPzAqzyHXbSSKNuN9")
-
-// Connect ---------------------------------------------------------------------
-// const  xrpl = require('xrpl') // For Node.js. In browsers, use <script>.
-const api = new xrpl.Client('wss://s.altnet.rippletest.net:51233')
-api.connect()
-api.on('connected', async () => {
-
-  // Get credentials from the Testnet Faucet -----------------------------------
-  console.log("Getting a wallet from the Testnet faucet...")
-  const {wallet, balance} = await api.fundWallet()
-
-  // Prepare transaction -------------------------------------------------------
-  const prepared = await api.autofill({
-    "TransactionType": "Payment",
-    "Account": wallet.address,
-    "Amount": xrpl.xrpToDrops("22"),
-    "Destination": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe"
-  })
-  const max_ledger = prepared.LastLedgerSequence
-  console.log("Prepared transaction instructions:", prepared)
-  console.log("Transaction cost:", xrpl.dropsToXrp(prepared.Fee), "XRP")
-  console.log("Transaction expires after ledger:", max_ledger)
-
-  // Sign prepared instructions ------------------------------------------------
-  const signed = wallet.sign(prepared)
-  console.log("Identifying hash:", signed.hash)
-  console.log("Signed blob:", signed.tx_blob)
-
-  // Submit signed blob --------------------------------------------------------
-  // The earliest ledger a transaction could appear in is the first ledger
-  // after the one that's already validated at the time it's *first* submitted.
-  const min_ledger = (await api.getLedgerIndex()) + 1
-  const result = await api.submit(signed.tx_blob)
-  console.log("Tentative result code:", result.result.engine_result)
-  console.log("Tentative result message:", result.result.engine_result_message)
-
-  // Wait for validation -------------------------------------------------------
-  let has_final_status = false
-  api.request({
-    "command": "subscribe",
-    "accounts": [wallet.address]
-  })
-  api.connection.on("transaction", (event) => {
-    if (event.transaction.hash == signed.hash) {
-      console.log("Transaction has executed!", event)
-      has_final_status = true
-    }
-  })
-  api.on('ledgerClosed', ledger => {
-    if (ledger.ledger_index > max_ledger && !has_final_status) {
-      console.log("Ledger version", ledger.ledger_index, "was validated.")
-      console.log("If the transaction hasn't succeeded by now, it's expired")
-      has_final_status = true
-    }
-  })
-
-  // There are other ways to do this, but they're more complicated.
-  // See https://xrpl.org/reliable-transaction-submission.html for details.
-  while (!has_final_status) {
-    await new Promise(resolve => setTimeout(resolve, 1000))
-  }
-
-  // Check transaction results -------------------------------------------------
-  try {
-    const tx = await api.request({
-      command: "tx",
-      transaction: signed.hash,
-      min_ledger: min_ledger,
-      max_ledger: max_ledger
-    })
-    if (tx.result.validated) {
-      console.log("This result is validated by consensus and final.")
-    } else {
-      console.log("This result is pending.")
-    }
-    console.log("Transaction result:", tx.result.meta.TransactionResult)
-
-    if (typeof tx.result.meta.delivered_amount === "string" &&
-        typeof tx.result.meta.delivered_amount !== "unavailable")
-    console.log("Delivered:", xrpl.dropsToXrp(tx.result.meta.delivered_amount), "XRP")
-  } catch(error) {
-    console.log("Couldn't get transaction outcome:", error)
-  }
-
-}) // End of api.on.('connected')