Merge branch 'xrpljs2.0' into update-freeze-code

content/_code-samples/get-started/js/base.js

@@ -1,3 +1,6 @@
+// In browsers, use a <script> tag. In Node.js, uncomment the following line:
+// const xrpl = require('xrpl')
+
 // Wrap code in an async function so we can use await
 async function main() {
 
@@ -7,7 +10,7 @@ async function main() {
 
   // ... custom code goes here
 
-  // Disconnect when done so Node.js can end the process
+  // Disconnect when done (If you omit this, Node.js won't end the process)
   client.disconnect()
 }
 

content/_code-samples/issue-a-token/js/issue-a-token.js

@@ -6,9 +6,6 @@
 if (typeof module !== "undefined") {
   // gotta use var here because const/let are block-scoped to the if statement.
   var xrpl = require('xrpl')
-} else {
-  // TODO: remove when webpack is fixed
-  var xrpl = ripple;
 }
 
 // Connect ---------------------------------------------------------------------
@@ -38,7 +35,7 @@ async function main() {
   const cst_prepared = await api.autofill(cold_settings_tx)
   const cst_signed = cold_wallet.sign(cst_prepared)
   console.log("Sending cold address AccountSet transaction...")
-  const cst_result = await api.submitSignedReliable(cst_signed.tx_blob)
+  const cst_result = await api.submitAndWait(cst_signed.tx_blob)
   if (cst_result.result.meta.TransactionResult == "tesSUCCESS") {
     console.log(`Transaction succeeded: https://testnet.xrpl.org/transactions/${cst_signed.hash}`)
   } else {
@@ -54,14 +51,14 @@ async function main() {
     "Domain": "6578616D706C652E636F6D", // "example.com"
     "SetFlag": 2 // enable Require Auth so we can't use trust lines that users
                  // make to the hot address, even by accident.
-    //"Flags": (api.txFlags.AccountSet.DisallowXRP |
-    //          api.txFlags.AccountSet.RequireDestTag)
+    //"Flags": (api.AccountSetAsfFlags.asfDisallowXRP |
+    //          api.AccountSetAsfFlags.asfRequireDestTag)
   }
 
   const hst_prepared = await api.autofill(hot_settings_tx)
   const hst_signed = hot_wallet.sign(hst_prepared)
   console.log("Sending hot address AccountSet transaction...")
-  const hst_result = await api.submitSignedReliable(hst_signed.tx_blob)
+  const hst_result = await api.submitAndWait(hst_signed.tx_blob)
   if (hst_result.result.meta.TransactionResult == "tesSUCCESS") {
     console.log(`Transaction succeeded: https://testnet.xrpl.org/transactions/${hst_signed.hash}`)
   } else {
@@ -84,7 +81,7 @@ async function main() {
   const ts_prepared = await api.autofill(trust_set_tx)
   const ts_signed = hot_wallet.sign(ts_prepared)
   console.log("Creating trust line from hot address to issuer...")
-  const ts_result = await api.submitSignedReliable(ts_signed.tx_blob)
+  const ts_result = await api.submitAndWait(ts_signed.tx_blob)
   if (ts_result.result.meta.TransactionResult == "tesSUCCESS") {
     console.log(`Transaction succeeded: https://testnet.xrpl.org/transactions/${ts_signed.hash}`)
   } else {
@@ -108,7 +105,7 @@ async function main() {
   const pay_prepared = await api.autofill(send_token_tx)
   const pay_signed = cold_wallet.sign(pay_prepared)
   console.log(`Sending ${issue_quantity} ${currency_code} to ${hot_wallet.address}...`)
-  const pay_result = await api.submitSignedReliable(pay_signed.tx_blob)
+  const pay_result = await api.submitAndWait(pay_signed.tx_blob)
   if (pay_result.result.meta.TransactionResult == "tesSUCCESS") {
     console.log(`Transaction succeeded: https://testnet.xrpl.org/transactions/${pay_signed.hash}`)
   } else {

content/_code-samples/require-destination-tags/require-destination-tags.js

@@ -29,7 +29,7 @@ async function main() {
   const signed = wallet.sign(prepared)
   console.log("Transaction hash:", signed.hash)
 
-  const submit_result = await client.submitSignedReliable(signed.tx_blob)
+  const submit_result = await client.submitAndWait(signed.tx_blob)
   console.log("Submit result:", submit_result)
 
 

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.submitAndWait(signed.tx_blob)
+  // This raises an exception if the transaction isn't confirmed.
+
+  // Wait for validation -------------------------------------------------------
+  // submitAndWait() 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')