docs: finalizes documentation for xrpl.js (#1703)

docs: Adds JSDoc comments to all functions and interfaces
2025-12-06 17:27:59 +00:00 · 2021-10-12 12:04:18 -07:00
parent df4c9dc2fd
commit 615504db22
136 changed files with 3869 additions and 501 deletions
--- a/snippets/src/decoder.ts
+++ b/snippets/src/decoder.ts
@@ -1,12 +1,16 @@
 // import * as codec from 'ripple-binary-codec'

-// const original = codec.decode(
-//   '12000022800200002400000001201B00EF81E661EC6386F26FC0FFFF0000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D166461968400000000000000C6940000000000000646AD3504529A0465E2E0000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D1664619732102F89EAEC7667B30F33D0687BBA86C3FE2A08CCA40A9186C5BDE2DAA6FA97A37D87446304402200A693FB5CA6B21250EBDFD8CFF526EE0DF7C9E4E31EB0660692E75E6A93BF5F802203CC39463DDA21386898CA31E18AD1A6828647D65741DD637BAD71BC83E29DB9481145E7B112523F68D2F5E879DB4EAC51C6698A693048314CA6EDC7A28252DAEA6F2045B24F4D7C333E146170112300000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D166461900'
-// )
+/*
+ * const original = codec.decode(
+ *   '12000022800200002400000001201B00EF81E661EC6386F26FC0FFFF0000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D166461968400000000000000C6940000000000000646AD3504529A0465E2E0000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D1664619732102F89EAEC7667B30F33D0687BBA86C3FE2A08CCA40A9186C5BDE2DAA6FA97A37D87446304402200A693FB5CA6B21250EBDFD8CFF526EE0DF7C9E4E31EB0660692E75E6A93BF5F802203CC39463DDA21386898CA31E18AD1A6828647D65741DD637BAD71BC83E29DB9481145E7B112523F68D2F5E879DB4EAC51C6698A693048314CA6EDC7A28252DAEA6F2045B24F4D7C333E146170112300000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D166461900'
+ * )
+ */

-// const test = codec.decode(
-//   '12000022800200002400000017201B008694F261EC6386F26FC0FFFF0000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D166461968400000000000000C6940000000000000646AD3504529A0465E2E0000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D1664619732102F89EAEC7667B30F33D0687BBA86C3FE2A08CCA40A9186C5BDE2DAA6FA97A37D874473045022100D8B57E8E06EAE27B1343AF8CAD3F501E18260CCF8BCED08066074106F0F191A3022058FEA6CE9E7FA69D1244C3A70F18983CC2DAF0B10CBB86A6677CF2A5D2B8A68081145E7B112523F68D2F5E879DB4EAC51C6698A693048314CA6EDC7A28252DAEA6F2045B24F4D7C333E146170112300000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D166461900'
-// )
+/*
+ * const test = codec.decode(
+ *   '12000022800200002400000017201B008694F261EC6386F26FC0FFFF0000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D166461968400000000000000C6940000000000000646AD3504529A0465E2E0000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D1664619732102F89EAEC7667B30F33D0687BBA86C3FE2A08CCA40A9186C5BDE2DAA6FA97A37D874473045022100D8B57E8E06EAE27B1343AF8CAD3F501E18260CCF8BCED08066074106F0F191A3022058FEA6CE9E7FA69D1244C3A70F18983CC2DAF0B10CBB86A6677CF2A5D2B8A68081145E7B112523F68D2F5E879DB4EAC51C6698A693048314CA6EDC7A28252DAEA6F2045B24F4D7C333E146170112300000000000000000000000005553440000000000054F6F784A58F9EFB0A9EB90B83464F9D166461900'
+ * )
+ */

 // console.log('original:', JSON.stringify(original))

--- a/snippets/src/getTransaction.ts
+++ b/snippets/src/getTransaction.ts
@@ -1,22 +1,26 @@
-// import {Client} from '../../dist/npm'
-// import {TransactionMetadata} from '../../src/models/common/transaction'
+/*
+ * import {Client} from '../../dist/npm'
+ * import {TransactionMetadata} from 'xrpl-local/models/common/transaction'
+ */

 // const client = new Client('wss://s.altnet.rippletest.net:51233')

 // getTransaction()

-// async function getTransaction() {
-//   await client.connect()
-//   const ledger = await client.request({command: 'ledger', transactions: true})
-//   console.log(ledger)
-//   const tx = await client.request({
-//     command: 'tx',
-//     transaction: ledger.result.ledger.transactions[0] as string
-//   })
-//   console.log(tx)
-//   console.log(
-//     'deliveredAmount:',
-//     (tx.result.meta as TransactionMetadata).DeliveredAmount
-//   )
-//   process.exit(0)
-// }
+/*
+ * async function getTransaction() {
+ *   await client.connect()
+ *   const ledger = await client.request({command: 'ledger', transactions: true})
+ *   console.log(ledger)
+ *   const tx = await client.request({
+ *     command: 'tx',
+ *     transaction: ledger.result.ledger.transactions[0] as string
+ *   })
+ *   console.log(tx)
+ *   console.log(
+ *     'deliveredAmount:',
+ *     (tx.result.meta as TransactionMetadata).DeliveredAmount
+ *   )
+ *   process.exit(0)
+ * }
+ */
--- a/snippets/src/parseAccountFlags.ts
+++ b/snippets/src/parseAccountFlags.ts
@@ -1,21 +1,25 @@
-// import {Client} from '../../dist/npm'
-// import {AccountFlags} from '../../dist/npm/common/constants'
+/*
+ * import {Client} from '../../dist/npm'
+ * import {AccountFlags} from '../../dist/npm/common/constants'
+ */

 // const client = new Client('wss://s.altnet.rippletest.net:51233')

 // parseAccountFlags()

-// async function parseAccountFlags() {
-//   await client.connect()
-//   const account_info = await client.request({
-//     command: 'account_info',
-//     account: 'rKsdkGhyZH6b2Zzd5hNnEqSv2wpznn4n6N'
-//   })
-//   const flags = account_info.result.account_data.Flags
-//   for (const flagName in AccountFlags) {
-//     if (flags & AccountFlags[flagName]) {
-//       console.log(`${flagName} enabled`)
-//     }
-//   }
-//   process.exit(0)
-// }
+/*
+ * async function parseAccountFlags() {
+ *   await client.connect()
+ *   const account_info = await client.request({
+ *     command: 'account_info',
+ *     account: 'rKsdkGhyZH6b2Zzd5hNnEqSv2wpznn4n6N'
+ *   })
+ *   const flags = account_info.result.account_data.Flags
+ *   for (const flagName in AccountFlags) {
+ *     if (flags & AccountFlags[flagName]) {
+ *       console.log(`${flagName} enabled`)
+ *     }
+ *   }
+ *   process.exit(0)
+ * }
+ */
--- a/snippets/src/paths.ts
+++ b/snippets/src/paths.ts
@@ -1,53 +1,63 @@
 // import {Client} from '../../dist/npm'

-// const client = new Client(
-//   // 'wss://s.altnet.rippletest.net:51233'
-//   // 'ws://35.158.96.209:51233'
-//   'ws://34.210.87.206:51233'
-// )
+/*
+ * const client = new Client(
+ *   // 'wss://s.altnet.rippletest.net:51233'
+ *   // 'ws://35.158.96.209:51233'
+ *   'ws://34.210.87.206:51233'
+ * )
+ */

 // sign()

-// async function sign() {
-//   await client.connect()
-//   const pathfind: any = {
-//     source: {
-//       address: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
-//       amount: {
-//         currency: 'drops',
-//         value: '100'
-//       }
-//     },
-//     destination: {
-//       address: 'rKT4JX4cCof6LcDYRz8o3rGRu7qxzZ2Zwj',
-//       amount: {
-//         currency: 'USD',
-//         counterparty: 'rVnYNK9yuxBz4uP8zC8LEFokM2nqH3poc'
-//       }
-//     }
-//   }
+/*
+ * async function sign() {
+ *   await client.connect()
+ *   const pathfind: any = {
+ *     source: {
+ *       address: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
+ *       amount: {
+ *         currency: 'drops',
+ *         value: '100'
+ *       }
+ *     },
+ *     destination: {
+ *       address: 'rKT4JX4cCof6LcDYRz8o3rGRu7qxzZ2Zwj',
+ *       amount: {
+ *         currency: 'USD',
+ *         counterparty: 'rVnYNK9yuxBz4uP8zC8LEFokM2nqH3poc'
+ *       }
+ *     }
+ *   }
+ */

-//   await client
-//     .getPaths(pathfind)
-//     .then(async (data) => {
-//       console.log('paths:', JSON.stringify(data))
-//       const fakeSecret = 'shsWGZcmZz6YsWWmcnpfr6fLTdtFV'
+/*
+ *   await client
+ *     .getPaths(pathfind)
+ *     .then(async (data) => {
+ *       console.log('paths:', JSON.stringify(data))
+ *       const fakeSecret = 'shsWGZcmZz6YsWWmcnpfr6fLTdtFV'
+ */

-//       pathfind.paths = data[0].paths
-//       pathfind.destination = data[0].destination
-//       await client
-//         .preparePayment('r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59', pathfind)
-//         .then((ret) => {
-//           const signed = client.sign(ret.txJSON, fakeSecret)
-//           console.log('signed:', signed)
-//         })
-//         .catch((err) => {
-//           console.log('ERR 1:', JSON.stringify(err))
-//         })
-//     })
-//     .catch((err) => {
-//       console.log('ERR 2:', err)
-//     })
+/*
+ *       pathfind.paths = data[0].paths
+ *       pathfind.destination = data[0].destination
+ *       await client
+ *         .preparePayment('r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59', pathfind)
+ *         .then((ret) => {
+ *           const signed = client.sign(ret.txJSON, fakeSecret)
+ *           console.log('signed:', signed)
+ *         })
+ *         .catch((err) => {
+ *           console.log('ERR 1:', JSON.stringify(err))
+ *         })
+ *     })
+ *     .catch((err) => {
+ *       console.log('ERR 2:', err)
+ *     })
+ */

-//   client.disconnect()
-// }
+/*
+ *   client.disconnect()
+ * }
+ */
--- a/snippets/src/reliableTransactionSubmission.ts
+++ b/snippets/src/reliableTransactionSubmission.ts
@@ -47,125 +47,139 @@
 //    */
 //   const payments = []

-//   const sourceAccount = (await generateTestnetAccount()).account
-//   console.log(
-//     `Generated new Testnet account: ${sourceAccount.classicAddress}/${sourceAccount.secret}`
-//   )
-//   // Send amounts from 1 drop to 10 drops
-//   for (let i = 1; i <= 10; i++) {
-//     payments.push({
-//       source: sourceAccount,
-//       destination: 'rhsoCozhUxwcyQgzFi1FVRoMVQgk7cZd4L', // Random Testnet destination
-//       amount_drops: i.toString()
-//     })
-//   }
-//   const results = await performPayments(payments)
-//   console.log(JSON.stringify(results, null, 2))
-//   process.exit(0)
-// }
+/*
+ *   const sourceAccount = (await generateTestnetAccount()).account
+ *   console.log(
+ *     `Generated new Testnet account: ${sourceAccount.classicAddress}/${sourceAccount.secret}`
+ *   )
+ *   // Send amounts from 1 drop to 10 drops
+ *   for (let i = 1; i <= 10; i++) {
+ *     payments.push({
+ *       source: sourceAccount,
+ *       destination: 'rhsoCozhUxwcyQgzFi1FVRoMVQgk7cZd4L', // Random Testnet destination
+ *       amount_drops: i.toString()
+ *     })
+ *   }
+ *   const results = await performPayments(payments)
+ *   console.log(JSON.stringify(results, null, 2))
+ *   process.exit(0)
+ * }
+ */

-// async function performPayments(payments) {
-//   const finalResults = []
-//   const txFinalizedPromises = []
-//   const client = new Client('wss://s.altnet.rippletest.net:51233')
-//   await client.connect()
+/*
+ * async function performPayments(payments) {
+ *   const finalResults = []
+ *   const txFinalizedPromises = []
+ *   const client = new Client('wss://s.altnet.rippletest.net:51233')
+ *   await client.connect()
+ */

-//   for (let i = 0; i < payments.length; i++) {
-//     const payment = payments[i]
-//     const account_info: AccountInfoResponse = await client.request({
-//       command: 'account_info',
-//       account: payment.source.classicAddress,
-//       ledger_index: 'current'
-//     })
-//     const sequence = account_info.result.account_data.Sequence
-//     const preparedPayment = await client.preparePayment(
-//       payment.source.classicAddress,
-//       {
-//         source: {
-//           address: payment.source.classicAddress,
-//           amount: {
-//             value: payment.amount_drops,
-//             currency: 'drops'
-//           }
-//         },
-//         destination: {
-//           address: payment.destination,
-//           minAmount: {
-//             value: payment.amount_drops,
-//             currency: 'drops'
-//           }
-//         }
-//       },
-//       {
-//         sequence
-//       }
-//     )
-//     const signed = client.sign(preparedPayment.txJSON, payment.source.secret)
-//     finalResults.push({
-//       id: signed.id
-//     })
-//     const response = await client.request({
-//       command: 'submit',
-//       tx_blob: signed.signedTransaction
-//     })
+/*
+ *   for (let i = 0; i < payments.length; i++) {
+ *     const payment = payments[i]
+ *     const account_info: AccountInfoResponse = await client.request({
+ *       command: 'account_info',
+ *       account: payment.source.classicAddress,
+ *       ledger_index: 'current'
+ *     })
+ *     const sequence = account_info.result.account_data.Sequence
+ *     const preparedPayment = await client.preparePayment(
+ *       payment.source.classicAddress,
+ *       {
+ *         source: {
+ *           address: payment.source.classicAddress,
+ *           amount: {
+ *             value: payment.amount_drops,
+ *             currency: 'drops'
+ *           }
+ *         },
+ *         destination: {
+ *           address: payment.destination,
+ *           minAmount: {
+ *             value: payment.amount_drops,
+ *             currency: 'drops'
+ *           }
+ *         }
+ *       },
+ *       {
+ *         sequence
+ *       }
+ *     )
+ *     const signed = client.sign(preparedPayment.txJSON, payment.source.secret)
+ *     finalResults.push({
+ *       id: signed.id
+ *     })
+ *     const response = await client.request({
+ *       command: 'submit',
+ *       tx_blob: signed.signedTransaction
+ *     })
+ */

-//     // Most of the time we'll get 'tesSUCCESS' or (after many submissions) 'terQUEUED'
-//     console.log(`tx ${i} - tentative: ${response.result.engine_result}`)
+/*
+ *     // Most of the time we'll get 'tesSUCCESS' or (after many submissions) 'terQUEUED'
+ *     console.log(`tx ${i} - tentative: ${response.result.engine_result}`)
+ */

-//     const txFinalizedPromise = new Promise<void>((resolve) => {
-//       const ledgerClosedCallback = async (event: LedgerClosedEvent) => {
-//         let status
-//         try {
-//           status = await client.request({command: 'tx', transaction: signed.id})
-//         } catch (e) {
-//           // Typical error when the tx hasn't been validated yet:
-//           if (e.name !== 'MissingLedgerHistoryError') {
-//             console.log(e)
-//           }
+/*
+ *     const txFinalizedPromise = new Promise<void>((resolve) => {
+ *       const ledgerClosedCallback = async (event: LedgerClosedEvent) => {
+ *         let status
+ *         try {
+ *           status = await client.request({command: 'tx', transaction: signed.id})
+ *         } catch (e) {
+ *           // Typical error when the tx hasn't been validated yet:
+ *           if (e.name !== 'MissingLedgerHistoryError') {
+ *             console.log(e)
+ *           }
+ */

-//           if (
-//             event.ledger_index >
-//             preparedPayment.instructions.maxLedgerVersion + 3
-//           ) {
-//             // Assumptions:
-//             // - We are still connected to the same rippled server
-//             // - No ledger gaps occurred
-//             // - All ledgers between the time we submitted the tx and now have been checked for the tx
-//             status = {
-//               finalResult:
-//                 'Transaction was not, and never will be, included in a validated ledger'
-//             }
-//           } else {
-//             // Check again later:
-//             client.connection.once('ledgerClosed', ledgerClosedCallback)
-//             return
-//           }
-//         }
+/*
+ *           if (
+ *             event.ledger_index >
+ *             preparedPayment.instructions.maxLedgerVersion + 3
+ *           ) {
+ *             // Assumptions:
+ *             // - We are still connected to the same rippled server
+ *             // - No ledger gaps occurred
+ *             // - All ledgers between the time we submitted the tx and now have been checked for the tx
+ *             status = {
+ *               finalResult:
+ *                 'Transaction was not, and never will be, included in a validated ledger'
+ *             }
+ *           } else {
+ *             // Check again later:
+ *             client.connection.once('ledgerClosed', ledgerClosedCallback)
+ *             return
+ *           }
+ *         }
+ */

-//         for (let j = 0; j < finalResults.length; j++) {
-//           if (finalResults[j].id === signed.id) {
-//             finalResults[j].result = status.address
-//               ? {
-//                   source: status.address,
-//                   destination: status.specification.destination.address,
-//                   deliveredAmount: status.outcome.deliveredAmount,
-//                   result: status.outcome.result,
-//                   timestamp: status.outcome.timestamp,
-//                   ledgerVersion: status.outcome.ledgerVersion
-//                 }
-//               : status
-//             process.stdout.write('.')
-//             return resolve()
-//           }
-//         }
-//       }
-//       client.connection.once('ledgerClosed', ledgerClosedCallback)
-//     })
-//     txFinalizedPromises.push(txFinalizedPromise)
-//   }
-//   await Promise.all(txFinalizedPromises)
-//   return finalResults
-// }
+/*
+ *         for (let j = 0; j < finalResults.length; j++) {
+ *           if (finalResults[j].id === signed.id) {
+ *             finalResults[j].result = status.address
+ *               ? {
+ *                   source: status.address,
+ *                   destination: status.specification.destination.address,
+ *                   deliveredAmount: status.outcome.deliveredAmount,
+ *                   result: status.outcome.result,
+ *                   timestamp: status.outcome.timestamp,
+ *                   ledgerVersion: status.outcome.ledgerVersion
+ *                 }
+ *               : status
+ *             process.stdout.write('.')
+ *             return resolve()
+ *           }
+ *         }
+ *       }
+ *       client.connection.once('ledgerClosed', ledgerClosedCallback)
+ *     })
+ *     txFinalizedPromises.push(txFinalizedPromise)
+ *   }
+ *   await Promise.all(txFinalizedPromises)
+ *   return finalResults
+ * }
+ */

 // /**
 //  * Generate a new Testnet account by requesting one from the faucet.
@@ -194,22 +208,24 @@
 //       response.on('end', () => {
 //         const body = Buffer.concat(chunks).toString()

-//         // "application/json; charset=utf-8"
-//         if (response.headers['content-type'].startsWith('application/json')) {
-//           resolve(JSON.parse(body))
-//         } else {
-//           reject({
-//             statusCode: response.statusCode,
-//             contentType: response.headers['content-type'],
-//             body
-//           })
-//         }
-//       })
-//     })
-//     request.on('error', (error) => {
-//       console.error(error)
-//       reject(error)
-//     })
-//     request.end()
-//   })
-// }
+/*
+ *         // "application/json; charset=utf-8"
+ *         if (response.headers['content-type'].startsWith('application/json')) {
+ *           resolve(JSON.parse(body))
+ *         } else {
+ *           reject({
+ *             statusCode: response.statusCode,
+ *             contentType: response.headers['content-type'],
+ *             body
+ *           })
+ *         }
+ *       })
+ *     })
+ *     request.on('error', (error) => {
+ *       console.error(error)
+ *       reject(error)
+ *     })
+ *     request.end()
+ *   })
+ * }
+ */