diff --git a/.eslintrc.js b/.eslintrc.js index ac4c4a8b..cdf04a59 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -47,6 +47,13 @@ module.exports = { // no-shadow has false-positives for enum, @typescript-eslint version fixes that 'no-shadow': 'off', '@typescript-eslint/no-shadow': ['error'], + 'multiline-comment-style': ['error', 'starred-block'], + 'jsdoc/check-examples': 'off', + + // Allows the usage of @category -- TODO: try to add this in base config + 'jsdoc/check-tag-names': 'off', + 'tsdoc/syntax': 'off', + 'jsdoc/require-description-complete-sentence': 'off', }, overrides: [ { diff --git a/README.md b/README.md index 2ac3752b..36a5d7fe 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,9 @@ A JavaScript/TypeScript library for interacting with the XRP Ledger This is the recommended library for integrating a JavaScript/TypeScript app with the XRP Ledger, especially if you intend to use advanced functionality such as IOUs, payment paths, the decentralized exchange, account settings, payment channels, escrows, multi-signing, and more. -## [➡️ Reference Documentation](https://xrpl.org/rippleapi-reference.html) - -See the full reference documentation on the XRP Ledger Dev Portal. - ## [➡️ Applications and Projects](APPLICATIONS.md) -What is xrpl.js used for? The applications on the list linked above use `xrpl.js`. Open a PR to add your app or project to the list! +What is `xrpl.js` used for? The applications on the list linked above use `xrpl.js`. Open a PR to add your app or project to the list! ### Features @@ -32,8 +28,8 @@ What is xrpl.js used for? The applications on the list linked above use `xrpl.js See also: [RippleAPI Beginners Guide](https://xrpl.org/get-started-with-rippleapi-for-javascript.html) In an existing project (with `package.json`), install `xrpl.js`: -``` -$ npm install xrpl@beta +```shell +npm install xrpl@beta ``` Then see the [documentation](#documentation). @@ -87,7 +83,7 @@ Until official support for [Deno](https://deno.land) is added, you can use the f import xrpl from 'https://dev.jspm.io/npm:xrpl'; (async () => { - const api = new (xrpl as any).RippleAPI({ server: 'wss://s.altnet.rippletest.net:51233' }); + const api = new (xrpl as any).Client('wss://s.altnet.rippletest.net:51233'); const address = 'rH8NxV12EuV...khfJ5uw9kT'; api.connect().then(() => { @@ -106,7 +102,7 @@ import xrpl from 'https://dev.jspm.io/npm:xrpl'; ### Mailing Lists -We have a low-traffic mailing list for announcements of new xrpl.js releases. (About 1 email per week) +We have a low-traffic mailing list for announcements of new `xrpl.js` releases. (About 1 email per week) + [Subscribe to xrpl-announce](https://groups.google.com/g/xrpl-announce) @@ -117,8 +113,8 @@ If you're using the XRP Ledger in production, you should run a [rippled server]( ## Development To build the library for Node.js and the browser: -``` -$ npm run build +```shell +npm run build ``` The TypeScript compiler will [output](./tsconfig.json#L7) the resulting JS files in `./dist/npm/`. diff --git a/package.json b/package.json index 92ed3a87..bd2b2e97 100644 --- a/package.json +++ b/package.json @@ -86,7 +86,7 @@ "analyze": "run-s build:web --analyze", "watch": "run-s build:lib --watch", "clean": "rm -rf dist", - "docgen": "typedoc ./src/index.ts", + "docgen": "typedoc", "prepublish": "run-s clean build", "test": "nyc mocha --config=test/.mocharc.json --exit", "test:integration": "TS_NODE_PROJECT=tsconfig.build.json nyc mocha ./test/integration/**/*.ts ./test/integration/*.ts", diff --git a/snippets/src/decoder.ts b/snippets/src/decoder.ts index 57b06b0a..f749eaa8 100644 --- 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)) diff --git a/snippets/src/getTransaction.ts b/snippets/src/getTransaction.ts index 2d0a5ddc..80f76533 100644 --- 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) + * } + */ diff --git a/snippets/src/parseAccountFlags.ts b/snippets/src/parseAccountFlags.ts index 9d62d679..555441f4 100644 --- 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) + * } + */ diff --git a/snippets/src/paths.ts b/snippets/src/paths.ts index f049e665..90ce2c4a 100644 --- 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() + * } + */ diff --git a/snippets/src/reliableTransactionSubmission.ts b/snippets/src/reliableTransactionSubmission.ts index 2b929f12..8c7290c9 100644 --- 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((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((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() + * }) + * } + */ diff --git a/src/client/backoff.ts b/src/client/backoff.ts index 064e03ac..d9f58c1b 100644 --- a/src/client/backoff.ts +++ b/src/client/backoff.ts @@ -1,14 +1,16 @@ -// Original code based on "backo" - https://github.com/segmentio/backo -// MIT License - Copyright 2014 Segment.io -// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation -// files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, -// modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software -// is furnished to do so, subject to the following conditions: -// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. -// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE -// WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR -// COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +/* + * Original code based on "backo" - https://github.com/segmentio/backo + * MIT License - Copyright 2014 Segment.io + * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation + * files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, + * modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software + * is furnished to do so, subject to the following conditions: + * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR + * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, + * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + */ interface ExponentialBackoffOptions { // The min backoff duration. diff --git a/src/client/broadcastClient.ts b/src/client/broadcastClient.ts index 86fe6bdf..4660f129 100644 --- a/src/client/broadcastClient.ts +++ b/src/client/broadcastClient.ts @@ -2,6 +2,8 @@ import { Client, ClientOptions } from '.' /** * Client that can rely on multiple different servers. + * + * @category Clients */ export default class BroadcastClient extends Client { private readonly clients: Client[] diff --git a/src/client/connection.ts b/src/client/connection.ts index d664d1a3..2e1fc790 100644 --- a/src/client/connection.ts +++ b/src/client/connection.ts @@ -45,11 +45,11 @@ interface ConnectionOptions { */ export type ConnectionUserOptions = Partial -// -// Represents an intentionally triggered web-socket disconnect code. -// WebSocket spec allows 4xxx codes for app/library specific codes. -// See: https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent -// +/** + * Represents an intentionally triggered web-socket disconnect code. + * WebSocket spec allows 4xxx codes for app/library specific codes. + * See: https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent + */ export const INTENTIONAL_DISCONNECT_CODE = 4000 type WebsocketState = 0 | 1 | 2 | 3 @@ -129,8 +129,10 @@ function createWebSocket( ) const websocketOptions = { ...options, ...optionsOverrides } const websocket = new WebSocket(url, websocketOptions) - // we will have a listener for each outstanding request, - // so we have to raise the limit (the default is 10) + /* + * we will have a listener for each outstanding request, + * so we have to raise the limit (the default is 10) + */ if (typeof websocket.setMaxListeners === 'function') { websocket.setMaxListeners(Infinity) } @@ -289,9 +291,11 @@ export class Connection extends EventEmitter { if (this.ws != null) { this.ws.once('close', (code) => resolve(code)) } - // Connection already has a disconnect handler for the disconnect logic. - // Just close the websocket manually (with our "intentional" code) to - // trigger that. + /* + * Connection already has a disconnect handler for the disconnect logic. + * Just close the websocket manually (with our "intentional" code) to + * trigger that. + */ if (this.ws != null && this.state !== WebSocket.CLOSING) { this.ws.close(INTENTIONAL_DISCONNECT_CODE) } @@ -302,9 +306,11 @@ export class Connection extends EventEmitter { * Disconnect the websocket, then connect again. */ public async reconnect(): Promise { - // NOTE: We currently have a "reconnecting" event, but that only triggers - // through an unexpected connection retry logic. - // See: https://github.com/XRPLF/xrpl.js/pull/1101#issuecomment-565360423 + /* + * NOTE: We currently have a "reconnecting" event, but that only triggers + * through an unexpected connection retry logic. + * See: https://github.com/XRPLF/xrpl.js/pull/1101#issuecomment-565360423 + */ this.emit('reconnect') await this.disconnect() await this.connect() @@ -465,8 +471,10 @@ export class Connection extends EventEmitter { const retryTimeout = this.retryConnectionBackoff.duration() this.trace('reconnect', `Retrying connection in ${retryTimeout}ms.`) this.emit('reconnecting', this.retryConnectionBackoff.attempts) - // Start the reconnect timeout, but set it to `this.reconnectTimeoutID` - // so that we can cancel one in-progress on disconnect. + /* + * Start the reconnect timeout, but set it to `this.reconnectTimeoutID` + * so that we can cancel one in-progress on disconnect. + */ this.reconnectTimeoutID = setTimeout(() => { this.reconnect().catch((error: Error) => { this.emit('error', 'reconnect', error.message, error) @@ -516,8 +524,10 @@ export class Connection extends EventEmitter { if (this.ws) { this.ws.removeAllListeners() this.ws.on('error', () => { - // Correctly listen for -- but ignore -- any future errors: If you - // don't have a listener on "error" node would log a warning on error. + /* + * Correctly listen for -- but ignore -- any future errors: If you + * don't have a listener on "error" node would log a warning on error. + */ }) this.ws.close() this.ws = null diff --git a/src/client/index.ts b/src/client/index.ts index a20c1126..029eb38a 100644 --- a/src/client/index.ts +++ b/src/client/index.ts @@ -166,16 +166,33 @@ const DEFAULT_MAX_FEE_XRP = '2' const MIN_LIMIT = 10 const MAX_LIMIT = 400 +const NORMAL_DISCONNECT_CODE = 1000 + +/** + * Client for interacting with rippled servers. + * + * @category Clients + */ class Client extends EventEmitter { - // New in > 0.21.0 - // non-validated ledger versions are allowed, and passed to rippled as-is. + /* + * Underlying connection to rippled. + */ public readonly connection: Connection - // Factor to multiply estimated fee by to provide a cushion in case the - // required fee rises during submission of a transaction. Defaults to 1.2. + /** + * Factor to multiply estimated fee by to provide a cushion in case the + * required fee rises during submission of a transaction. Defaults to 1.2. + * + * @category Fee + */ public readonly feeCushion: number - // Maximum fee to use with transactions, in XRP. Must be a string-encoded - // number. Defaults to '2'. + + /** + * Maximum transaction cost to allow, in decimal XRP. Must be a string-encoded + * number. Defaults to '2'. + * + * @category Fee + */ public readonly maxFeeXRP: string /** @@ -183,6 +200,7 @@ class Client extends EventEmitter { * * @param server - URL of the server to connect to. * @param options - Options for client settings. + * @category Constructor */ // eslint-disable-next-line max-lines-per-function -- okay because we have to set up all the connection handlers public constructor(server: string, options: ClientOptions = {}) { @@ -208,10 +226,12 @@ class Client extends EventEmitter { this.connection.on('disconnected', (code: number) => { let finalCode = code - // 4000: Connection uses a 4000 code internally to indicate a manual disconnect/close - // Since 4000 is a normal disconnect reason, we convert this to the standard exit code 1000 + /* + * 4000: Connection uses a 4000 code internally to indicate a manual disconnect/close + * Since 4000 is a normal disconnect reason, we convert this to the standard exit code 1000 + */ if (finalCode === INTENTIONAL_DISCONNECT_CODE) { - finalCode = 1000 + finalCode = NORMAL_DISCONNECT_CODE } this.emit('disconnected', finalCode) }) @@ -246,6 +266,16 @@ class Client extends EventEmitter { }) } + /** + * Get the url that the client is connected to. + * + * @returns The URL of the server this client is connected to. + * @category Network + */ + public get url(): string { + return this.connection.getUrl() + } + /** * Returns true if there are more pages of data. * @@ -256,11 +286,15 @@ class Client extends EventEmitter { * * @param response - Response to check for more pages on. * @returns Whether the response has more pages of data. + * @category Network */ public static hasNextPage(response: MarkerResponse): boolean { return Boolean(response.result.marker) } + /** + * @category Network + */ public async request( r: AccountChannelsRequest, ): Promise @@ -317,6 +351,7 @@ class Client extends EventEmitter { * * @param req - Request to send to the server. * @returns The response from the server. + * @category Network */ public async request( req: R, @@ -335,6 +370,9 @@ class Client extends EventEmitter { return response } + /** + * @category Network + */ public async requestNextPage( req: AccountChannelsRequest, resp: AccountChannelsResponse, @@ -380,6 +418,27 @@ class Client extends EventEmitter { return this.request(nextPageRequest) as unknown as U } + /** + * Event handler for subscription streams. + * + * @example + * ```ts + * const api = new Client('wss://s.altnet.rippletest.net:51233') + * + * api.on('transactions', (tx: TransactionStream) => { + * console.log("Received Transaction") + * console.log(tx) + * }) + * + * await api.connect() + * const response = await api.request({ + * command: 'subscribe', + * streams: ['transactions_proposed'] + * }) + * ``` + * + * @category Network + */ public on( event: 'ledgerClosed', listener: (ledger: LedgerStream) => void, @@ -401,7 +460,7 @@ class Client extends EventEmitter { listener: (phase: ConsensusStream) => void, ): this public on(event: 'path_find', listener: (path: PathFindStream) => void): this - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- actually needs to be any here + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- needs to be any for overload public on(event: 'error', listener: (...err: any[]) => void): this /** * Event handler for subscription streams. @@ -410,15 +469,14 @@ class Client extends EventEmitter { * @param listener - Function to run on event. * @returns This, because it inherits from EventEmitter. */ - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- actually needs to be any here + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- needs to be any for overload public on(eventName: string, listener: (...args: any[]) => void): this { - // if (args[0]?.type === 'transaction') { - // handlePartialPaymentStream(args[0]) - // } - return super.on(eventName, listener) } + /** + * @category Network + */ public async requestAll( req: AccountChannelsRequest, ): Promise @@ -456,14 +514,18 @@ class Client extends EventEmitter { request: T, collect?: string, ): Promise { - // The data under collection is keyed based on the command. Fail if command - // not recognized and collection key not provided. + /* + * The data under collection is keyed based on the command. Fail if command + * not recognized and collection key not provided. + */ const collectKey = collect ?? getCollectKeyFromCommand(request.command) if (!collectKey) { throw new ValidationError(`no collect key for command ${request.command}`) } - // If limit is not provided, fetches all data over multiple requests. - // NOTE: This may return much more than needed. Set limit when possible. + /* + * If limit is not provided, fetches all data over multiple requests. + * NOTE: This may return much more than needed. Set limit when possible. + */ const countTo: number = request.limit == null ? Infinity : request.limit let count = 0 let marker: unknown = request.marker @@ -503,6 +565,7 @@ class Client extends EventEmitter { * Tells the Client instance to connect to its rippled server. * * @returns A promise that resolves with a void value when a connection is established. + * @category Network */ public async connect(): Promise { return this.connection.connect() @@ -512,10 +575,13 @@ class Client extends EventEmitter { * Tells the Client instance to disconnect from it's rippled server. * * @returns A promise that resolves with a void value when a connection is destroyed. + * @category Network */ public async disconnect(): Promise { - // backwards compatibility: connection.disconnect() can return a number, but - // this method returns nothing. SO we await but don't return any result. + /* + * backwards compatibility: connection.disconnect() can return a number, but + * this method returns nothing. SO we await but don't return any result. + */ await this.connection.disconnect() } @@ -523,29 +589,67 @@ class Client extends EventEmitter { * Checks if the Client instance is connected to its rippled server. * * @returns Whether the client instance is connected. + * @category Network */ public isConnected(): boolean { return this.connection.isConnected() } - // syntactic sugar - + /** + * @category Core + */ public autofill = autofill - // @deprecated Use autofill instead - public prepareTransaction = autofill + /** + * @category Fee + */ public getFee = getFee - public getLedgerIndex = getLedgerIndex + /** + * @category Core + */ public submit = submit + /** + * @category Core + */ public submitSigned = submitSigned + /** + * @category Core + */ public submitReliable = submitReliable + /** + * @category Core + */ public submitSignedReliable = submitSignedReliable + /** + * @deprecated Use autofill instead, provided for users familiar with v1 + */ + public prepareTransaction = autofill + + /** + * @category Abstraction + */ public getXrpBalance = getXrpBalance + + /** + * @category Abstraction + */ public getBalances = getBalances + + /** + * @category Abstraction + */ public getOrderbook = getOrderbook + /** + * @category Abstraction + */ + public getLedgerIndex = getLedgerIndex + + /** + * @category Faucet + */ public fundWallet = fundWallet } diff --git a/src/client/partialPayment.ts b/src/client/partialPayment.ts index b178e250..1830243f 100644 --- a/src/client/partialPayment.ts +++ b/src/client/partialPayment.ts @@ -127,7 +127,7 @@ export function handlePartialPayment( /** * Check a transaction from a subscription stream for partial payment. * - * @param stream - Stream Transaction to check for partial payment,. + * @param stream - Stream Transaction to check for partial payment. */ export function handleStreamPartialPayment(stream: TransactionStream): void { if (isPartialPayment(stream.transaction, stream.meta)) { diff --git a/src/client/requestManager.ts b/src/client/requestManager.ts index e95694c2..3a44423e 100644 --- a/src/client/requestManager.ts +++ b/src/client/requestManager.ts @@ -112,8 +112,10 @@ export default class RequestManager { () => this.reject(newId, new TimeoutError()), timeout, ) - // Node.js won't exit if a timer is still running, so we tell Node to ignore. - // (Node will still wait for the request to complete). + /* + * Node.js won't exit if a timer is still running, so we tell Node to ignore. + * (Node will still wait for the request to complete). + */ // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Reason above. if (timer.unref) { timer.unref() diff --git a/src/errors.ts b/src/errors.ts index 6bbda5c8..ce70dc59 100644 --- a/src/errors.ts +++ b/src/errors.ts @@ -3,6 +3,12 @@ import { inspect } from 'util' // TODO: replace all `new Error`s with `new XrplError`s +/** + * Base Error class for xrpl.js. All Errors thrown by xrpl.js should throw + * XrplErrors. + * + * @category Errors + */ class XrplError extends Error { public readonly name: string public readonly message: string @@ -52,28 +58,84 @@ class XrplError extends Error { } } +/** + * Error thrown when rippled responds with an error. + * + * @category Errors + */ class RippledError extends XrplError {} +/** + * Error thrown when xrpl.js cannot specify error type. + * + * @category Errors + */ class UnexpectedError extends XrplError {} -class LedgerVersionError extends XrplError {} - +/** + * Error thrown when xrpl.js has an error with connection to rippled. + * + * @category Errors + */ class ConnectionError extends XrplError {} +/** + * Error thrown when xrpl.js is not connected to rippled server. + * + * @category Errors + */ class NotConnectedError extends ConnectionError {} +/** + * Error thrown when xrpl.js has disconnected from rippled server. + * + * @category Errors + */ class DisconnectedError extends ConnectionError {} +/** + * Error thrown when rippled is not initialized. + * + * @category Errors + */ class RippledNotInitializedError extends ConnectionError {} +/** + * Error thrown when xrpl.js times out. + * + * @category Errors + */ class TimeoutError extends ConnectionError {} +/** + * Error thrown when xrpl.js sees a response in the wrong format. + * + * @category Errors + */ class ResponseFormatError extends ConnectionError {} +/** + * Error thrown when xrpl.js sees a malformed transaction. + * + * @category Errors + */ class ValidationError extends XrplError {} +/** + * Error thrown when a client cannot generate a wallet from the testnet/devnet + * faucets, or when the client cannot infer the faucet URL (i.e. when the Client + * is connected to mainnet). + * + * @category Errors + */ class XRPLFaucetError extends XrplError {} +/** + * Error thrown when xrpl.js cannot retrieve a transaction, ledger, account, etc. + * From rippled. + * + * @category Errors + */ class NotFoundError extends XrplError { /** * Construct an XrplError. @@ -97,6 +159,5 @@ export { ResponseFormatError, ValidationError, NotFoundError, - LedgerVersionError, XRPLFaucetError, } diff --git a/src/models/ledger/accountRoot.ts b/src/models/ledger/accountRoot.ts index 6dc3ec6b..a336cfc6 100644 --- a/src/models/ledger/accountRoot.ts +++ b/src/models/ledger/accountRoot.ts @@ -1,21 +1,76 @@ import BaseLedgerEntry from './baseLedgerEntry' +/** + * The AccountRoot object type describes a single account, its settings, and + * XRP balance. + * + * @category Ledger Entries + */ export default interface AccountRoot extends BaseLedgerEntry { LedgerEntryType: 'AccountRoot' + /** The identifying (classic) address of this account. */ Account: string + /** The account's current XRP balance in drops, represented as a string. */ Balance: string + /** A bit-map of boolean flags enabled for this account. */ Flags: number + /** + * The number of objects this account owns in the ledger, which contributes + * to its owner reserve. + */ OwnerCount: number + /** + * The identifying hash of the transaction that most recently modified this + * object. + */ PreviousTxnID: string + /** + * The index of the ledger that contains the transaction that most recently + * modified this object. + */ PreviousTxnLgrSeq: number + /** The sequence number of the next valid transaction for this account. */ Sequence: number + /** + * The identifying hash of the transaction most recently sent by this + * account. This field must be enabled to use the AccountTxnID transaction + * field. To enable it, send an AccountSet transaction with the. + * `asfAccountTxnID` flag enabled. + */ AccountTxnID?: string + /** + * A domain associated with this account. In JSON, this is the hexadecimal + * for the ASCII representation of the domain. + */ Domain?: string + /** The md5 hash of an email address. */ EmailHash?: string + /** + * A public key that may be used to send encrypted messages to this account + * in JSON, uses hexadecimal. + */ MessageKey?: string + /** + * The address of a key pair that can be used to sign transactions for this + * account instead of the master key. Use a SetRegularKey transaction to + * change this value. + */ RegularKey?: string + /** + * How many Tickets this account owns in the ledger. This is updated + * automatically to ensure that the account stays within the hard limit of 250. + * Tickets at a time. + */ TicketCount?: number + /** + * How many significant digits to use for exchange rates of Offers involving + * currencies issued by this address. Valid values are 3 to 15, inclusive. + */ TickSize?: number + /** + * A transfer fee to charge other users for sending currency issued by this + * account to each other. + */ TransferRate?: number } diff --git a/src/models/ledger/amendments.ts b/src/models/ledger/amendments.ts index 60a0f599..a79405b0 100644 --- a/src/models/ledger/amendments.ts +++ b/src/models/ledger/amendments.ts @@ -2,14 +2,38 @@ import BaseLedgerEntry from './baseLedgerEntry' interface Majority { Majority: { + /** The Amendment ID of the pending amendment. */ Amendment: string + /** + * The `close_time` field of the ledger version where this amendment most + * recently gained a majority. + */ CloseTime: number } } +/** + * The Amendments object type contains a list of Amendments that are currently + * active. + * + * @category Ledger Entries + */ export default interface Amendments extends BaseLedgerEntry { LedgerEntryType: 'Amendments' + /** + * Array of 256-bit amendment IDs for all currently-enabled amendments. If + * omitted, there are no enabled amendments. + */ Amendments?: string[] + /** + * Array of objects describing the status of amendments that have majority + * support but are not yet enabled. If omitted, there are no pending + * amendments with majority support. + */ Majorities?: Majority[] + /** + * A bit-map of boolean flags. No flags are defined for the Amendments object + * type, so this value is always 0. + */ Flags: 0 } diff --git a/src/models/ledger/check.ts b/src/models/ledger/check.ts index 94ad3ace..15951a7a 100644 --- a/src/models/ledger/check.ts +++ b/src/models/ledger/check.ts @@ -2,19 +2,69 @@ import { Amount } from '../common' import BaseLedgerEntry from './baseLedgerEntry' +/** + * A Check object describes a check, similar to a paper personal check, which + * can be cashed by its destination to get money from its sender. + * + * @category Ledger Entries + */ export default interface Check extends BaseLedgerEntry { LedgerEntryType: 'Check' + /** The sender of the Check. Cashing the Check debits this address's balance. */ Account: string + /** + * The intended recipient of the Check. Only this address can cash the Check, + * using a CheckCash transaction. + */ Destination: string + /** + * A bit-map of boolean flags. No flags are defined for Checks, so this value + * is always 0. + */ Flags: 0 + /** + * A hint indicating which page of the sender's owner directory links to this + * object, in case the directory consists of multiple pages. + */ OwnerNode: string + /** + * The identifying hash of the transaction that most recently modified this + * object. + */ PreviousTxnID: string + /** + * The index of the ledger that contains the transaction that most recently + * modified this object. + */ PreviousTxnLgrSeq: number + /** + * The maximum amount of currency this Check can debit the sender. If the + * Check is successfully cashed, the destination is credited in the same + * currency for up to this amount. + */ SendMax: Amount + /** The sequence number of the CheckCreate transaction that created this check. */ Sequence: number + /** + * A hint indicating which page of the destination's owner directory links to + * this object, in case the directory consists of multiple pages. + */ DestinationNode?: string + /** + * An arbitrary tag to further specify the destination for this Check, such + * as a hosted recipient at the destination address. + */ DestinationTag?: number + /** Indicates the time after which this Check is considered expired. */ Expiration?: number + /** + * Arbitrary 256-bit hash provided by the sender as a specific reason or + * identifier for this Check. + */ InvoiceID?: string + /** + * An arbitrary tag to further specify the source for this Check, such as a + * hosted recipient at the sender's address. + */ SourceTag?: number } diff --git a/src/models/ledger/depositPreauth.ts b/src/models/ledger/depositPreauth.ts index cd41a39a..905b27fc 100644 --- a/src/models/ledger/depositPreauth.ts +++ b/src/models/ledger/depositPreauth.ts @@ -1,11 +1,35 @@ import BaseLedgerEntry from './baseLedgerEntry' +/** + * A DepositPreauth object tracks a preauthorization from one account to + * another. DepositPreauth transactions create these objects. + * + * @category Ledger Entries + */ export default interface DepositPreauth extends BaseLedgerEntry { LedgerEntryType: 'DepositPreauth' + /** The account that granted the preauthorization. */ Account: string + /** The account that received the preauthorization. */ Authorize: string + /** + * A bit-map of boolean flags. No flags are defined for DepositPreauth + * objects, so this value is always 0. + */ Flags: 0 + /** + * A hint indicating which page of the sender's owner directory links to this + * object, in case the directory consists of multiple pages. + */ OwnerNode: string + /** + * The identifying hash of the transaction that most recently modified this + * object. + */ PreviousTxnID: string + /** + * The index of the ledger that contains the transaction that most recently + * modified this object. + */ PreviousTxnLgrSeq: number } diff --git a/src/models/ledger/directoryNode.ts b/src/models/ledger/directoryNode.ts index 2d5b717d..3437eca5 100644 --- a/src/models/ledger/directoryNode.ts +++ b/src/models/ledger/directoryNode.ts @@ -1,15 +1,46 @@ import BaseLedgerEntry from './baseLedgerEntry' +/** + * The DirectoryNode object type provides a list of links to other objects in + * the ledger's state tree. + * + * @category Ledger Entries + */ export default interface DirectoryNode extends BaseLedgerEntry { LedgerEntryType: 'DirectoryNode' + /** + * A bit-map of boolean flags enabled for this directory. Currently, the + * protocol defines no flags for DirectoryNode objects. + */ Flags: number + /** The ID of root object for this directory. */ RootIndex: string + /** The contents of this Directory: an array of IDs of other objects. */ Indexes: string[] + /** + * If this Directory consists of multiple pages, this ID links to the next + * object in the chain, wrapping around at the end. + */ IndexNext?: number + /** + * If this Directory consists of multiple pages, this ID links to the + * previous object in the chain, wrapping around at the beginning. + */ IndexPrevious?: number + /** The address of the account that owns the objects in this directory. */ Owner?: string + /** + * The currency code of the TakerPays amount from the offers in this + * directory. + */ TakerPaysCurrency?: string + /** The issuer of the TakerPays amount from the offers in this directory. */ TakerPaysIssuer?: string + /** + * The currency code of the TakerGets amount from the offers in this + * directory. + */ TakerGetsCurrency?: string + /** The issuer of the TakerGets amount from the offers in this directory. */ TakerGetsIssuer?: string } diff --git a/src/models/ledger/escrow.ts b/src/models/ledger/escrow.ts index da04c685..11e26377 100644 --- a/src/models/ledger/escrow.ts +++ b/src/models/ledger/escrow.ts @@ -1,18 +1,74 @@ import BaseLedgerEntry from './baseLedgerEntry' +/** + * The Escrow object type represents a held payment of XRP waiting to be + * executed or canceled. + * + * @category Ledger Entries + */ export default interface Escrow extends BaseLedgerEntry { LedgerEntryType: 'Escrow' + /** + * The address of the owner (sender) of this held payment. This is the + * account that provided the XRP, and gets it back if the held payment is + * canceled. + */ Account: string + /** + * The destination address where the XRP is paid if the held payment is + * successful. + */ Destination: string + /** The amount of XRP, in drops, to be delivered by the held payment. */ Amount: string + /** + * A PREIMAGE-SHA-256 crypto-condition, as hexadecimal. If present, the + * EscrowFinish transaction must contain a fulfillment that satisfies this + * condition. + */ Condition?: string + /** + * The time after which this Escrow is considered expired. + */ CancelAfter?: number + /** + * The time, in seconds, since the Ripple Epoch, after which this held payment + * can be finished. Any EscrowFinish transaction before this time fails. + */ FinishAfter?: number + /** + * A bit-map of boolean flags. No flags are defined for the Escrow type, so + * this value is always 0. + */ Flags: number + /** + * An arbitrary tag to further specify the source for this held payment, such + * as a hosted recipient at the owner's address. + */ SourceTag?: number + /** + * An arbitrary tag to further specify the destination for this held payment, + * such as a hosted recipient at the destination address. + */ DestinationTag?: number + /** + * A hint indicating which page of the owner directory links to this object, + * in case the directory consists of multiple pages. + */ OwnerNode: string + /** + * A hint indicating which page of the destination's owner directory links to + * this object, in case the directory consists of multiple pages. + */ DestinationNode?: string + /** + * The identifying hash of the transaction that most recently modified this + * object. + */ PreviousTxnID: string + /** + * The index of the ledger that contains the transaction that most recently + * modified this object. + */ PreviousTxnLgrSeq: number } diff --git a/src/models/ledger/feeSettings.ts b/src/models/ledger/feeSettings.ts index ae79b37c..e9aa7567 100644 --- a/src/models/ledger/feeSettings.ts +++ b/src/models/ledger/feeSettings.ts @@ -1,10 +1,27 @@ import BaseLedgerEntry from './baseLedgerEntry' +/** + * The FeeSettings object type contains the current base transaction cost and + * reserve amounts as determined by fee voting. + * + * @category Ledger Entries + */ export default interface FeeSettings extends BaseLedgerEntry { LedgerEntryType: 'FeeSettings' + /** + * The transaction cost of the "reference transaction" in drops of XRP as + * hexadecimal. + */ BaseFee: string + /** The BaseFee translated into "fee units". */ ReferenceFeeUnits: number + /** The base reserve for an account in the XRP Ledger, as drops of XRP. */ ReserveBase: number + /** The incremental owner reserve for owning objects, as drops of XRP. */ ReserveIncrement: number + /** + * A bit-map of boolean flags for this object. No flags are defined for this + * type. + */ Flags: number } diff --git a/src/models/ledger/ledger.ts b/src/models/ledger/ledger.ts index 7ff61f87..f268bc04 100644 --- a/src/models/ledger/ledger.ts +++ b/src/models/ledger/ledger.ts @@ -3,19 +3,64 @@ import TransactionMetadata from '../transactions/metadata' import LedgerEntry from './ledgerEntry' +/** + * A ledger is a block of transactions and shared state data. It has a unique + * header that describes its contents using cryptographic hashes. + * + * @category Ledger Entries + */ export default interface Ledger { + /** The SHA-512Half of this ledger's state tree information. */ account_hash: string + /** All the state information in this ledger. */ accountState?: LedgerEntry[] + /** A bit-map of flags relating to the closing of this ledger. */ close_flags: number + /** + * The approximate time this ledger version closed, as the number of seconds + * since the Ripple Epoch of 2000-01-01 00:00:00. This value is rounded based + * on the close_time_resolution. + */ close_time: number + /** + * The approximate time this ledger was closed, in human-readable format. + * Always uses the UTC time zone. + */ close_time_human: string + /** + * An integer in the range [2,120] indicating the maximum number of seconds + * by which the close_time could be rounded. + */ close_time_resolution: number + /** Whether or not this ledger has been closed. */ closed: boolean + /** + * The SHA-512Half of this ledger version. This serves as a unique identifier + * for this ledger and all its contents. + */ ledger_hash: string + /** + * The ledger index of the ledger. Some API methods display this as a quoted + * integer; some display it as a native JSON number. + */ ledger_index: string + /** The approximate time at which the previous ledger was closed. */ parent_close_time: number + /** + * Unique identifying hash of the ledger that came immediately before this + * one. + */ parent_hash: string + /** Total number of XRP drops in the network, as a quoted integer. */ total_coins: string + /** Hash of the transaction information included in this ledger, as hex. */ transaction_hash: string + /** + * Transactions applied in this ledger version. By default, members are the + * transactions' identifying Hash strings. If the request specified expand as + * true, members are full representations of the transactions instead, in + * either JSON or binary depending on whether the request specified binary + * as true. + */ transactions?: Array } diff --git a/src/models/ledger/ledgerHashes.ts b/src/models/ledger/ledgerHashes.ts index 8aac96c3..a749d4e9 100644 --- a/src/models/ledger/ledgerHashes.ts +++ b/src/models/ledger/ledgerHashes.ts @@ -1,8 +1,24 @@ import BaseLedgerEntry from './baseLedgerEntry' +/** + * The LedgerHashes objects exist to make it possible to look up a previous + * ledger's hash with only the current ledger version and at most one lookup of + * a previous ledger version. + * + * @category Ledger Entries + */ export default interface LedgerHashes extends BaseLedgerEntry { LedgerEntryType: 'LedgerHashes' + /** The Ledger Index of the last entry in this object's Hashes array. */ LastLedgerSequence?: number + /** + * An array of up to 256 ledger hashes. The contents depend on which sub-type + * of LedgerHashes object this is. + */ Hashes: string[] + /** + * A bit-map of boolean flags for this object. No flags are defined for this + * type. + */ Flags: number } diff --git a/src/models/ledger/negativeUNL.ts b/src/models/ledger/negativeUNL.ts index 948691d1..7403c7b3 100644 --- a/src/models/ledger/negativeUNL.ts +++ b/src/models/ledger/negativeUNL.ts @@ -5,9 +5,26 @@ interface DisabledValidator { PublicKey: string } +/** + * The NegativeUNL object type contains the current status of the Negative UNL, + * a list of trusted validators currently believed to be offline. + * + * @category Ledger Entries + */ export default interface NegativeUNL extends BaseLedgerEntry { LedgerEntryType: 'NegativeUNL' + /** + * A list of trusted validators that are currently disabled. + */ DisabledValidators?: DisabledValidator[] + /** + * The public key of a trusted validator that is scheduled to be disabled in + * the next flag ledger. + */ ValidatorToDisable?: string + /** + * The public key of a trusted validator in the Negative UNL that is + * scheduled to be re-enabled in the next flag ledger. + */ ValidatorToReEnable?: string } diff --git a/src/models/ledger/offer.ts b/src/models/ledger/offer.ts index 72c0d87f..b5bdd825 100644 --- a/src/models/ledger/offer.ts +++ b/src/models/ledger/offer.ts @@ -4,16 +4,45 @@ import BaseLedgerEntry from './baseLedgerEntry' export default interface Offer extends BaseLedgerEntry { LedgerEntryType: 'Offer' + /** A bit-map of boolean flags enabled for this Offer. */ Flags: number + /** The address of the account that placed this Offer. */ Account: string + /** + * The Sequence value of the OfferCreate transaction that created this Offer + * object. Used in combination with the Account to identify this Offer. + */ Sequence: number + /** The remaining amount and type of currency requested by the Offer creator. */ TakerPays: Amount + /** + * The remaining amount and type of currency being provided by the Offer + * creator. + */ TakerGets: Amount + /** The ID of the Offer Directory that links to this Offer. */ BookDirectory: string + /** + * A hint indicating which page of the Offer Directory links to this object, + * in case the directory consists of multiple pages. + */ BookNode: string + /** + * A hint indicating which page of the Owner Directory links to this object, + * in case the directory consists of multiple pages. + */ OwnerNode: string + /** + * The identifying hash of the transaction that most recently modified this + * object. + */ PreviousTxnID: string + /** + * The index of the ledger that contains the transaction that most recently + * modified this object. + */ PreviousTxnLgrSeq: number + /** The time this Offer expires, in seconds since the Ripple Epoch. */ Expiration?: number } diff --git a/src/models/ledger/payChannel.ts b/src/models/ledger/payChannel.ts index 94977de7..c2210c35 100644 --- a/src/models/ledger/payChannel.ts +++ b/src/models/ledger/payChannel.ts @@ -1,20 +1,107 @@ import BaseLedgerEntry from './baseLedgerEntry' +/** + * The PayChannel object type represents a payment channel. Payment channels + * enable small, rapid off-ledger payments of XRP that can be later reconciled + * with the consensus ledger. A payment channel holds a balance of XRP that can + * only be paid out to a specific destination address until the channel is + * closed. + * + * @category Ledger Entries + */ export default interface PayChannel extends BaseLedgerEntry { LedgerEntryType: 'PayChannel' + /** + * The source address that owns this payment channel. This comes from the + * sending address of the transaction that created the channel. + */ Account: string + /** + * The destination address for this payment channel. While the payment + * channel is open, this address is the only one that can receive XRP from the + * channel. This comes from the Destination field of the transaction that + * created the channel. + */ Destination: string + /** + * Total XRP, in drops, that has been allocated to this channel. This + * includes XRP that has been paid to the destination address. This is + * initially set by the transaction that created the channel and can be + * increased if the source address sends a PaymentChannelFund transaction. + */ Amount: string + /** + * Total XRP, in drops, already paid out by the channel. The difference + * between this value and the Amount field is how much XRP can still be paid + * to the destination address with PaymentChannelClaim transactions. If the + * channel closes, the remaining difference is returned to the source address. + */ Balance: string + /** + * Public key, in hexadecimal, of the key pair that can be used to sign + * claims against this channel. This can be any valid secp256k1 or Ed25519 + * public key. This is set by the transaction that created the channel and + * must match the public key used in claims against the channel. The channel + * source address can also send XRP from this channel to the destination + * without signed claims. + */ PublicKey: string + /** + * Number of seconds the source address must wait to close the channel if + * it still has any XRP in it. Smaller values mean that the destination + * address has less time to redeem any outstanding claims after the source + * address requests to close the channel. Can be any value that fits in a + * 32-bit unsigned integer (0 to 2^32-1). This is set by the transaction that + * creates the channel. + */ SettleDelay: number + /** + * A hint indicating which page of the source address's owner directory links + * to this object, in case the directory consists of multiple pages. + */ OwnerNode: string + /** + * The identifying hash of the transaction that most recently modified this + * object. + */ PreviousTxnID: string + /** + * The index of the ledger that contains the transaction that most recently + * modified this object. + */ PreviousTxnLgrSeq: number + /** + * A bit-map of boolean flags enabled for this payment channel. Currently, + * the protocol defines no flags for PayChannel objects. + */ Flags: number + /** + * The mutable expiration time for this payment channel, in seconds since the + * Ripple Epoch. The channel is expired if this value is present and smaller + * than the previous ledger's close_time field. See Setting Channel Expiration + * for more details. + */ Expiration?: number + /** + * The immutable expiration time for this payment channel, in seconds since + * the Ripple Epoch. This channel is expired if this value is present and + * smaller than the previous ledger's close_time field. This is optionally + * set by the transaction that created the channel, and cannot be changed. + */ CancelAfter?: number + /** + * An arbitrary tag to further specify the source for this payment channel + * useful for specifying a hosted recipient at the owner's address. + */ SourceTag?: number + /** + * An arbitrary tag to further specify the destination for this payment + * channel, such as a hosted recipient at the destination address. + */ DestinationTag?: number + /** + * A hint indicating which page of the destination's owner directory links to + * this object, in case the directory consists of multiple pages. + */ DestinationNode?: string } diff --git a/src/models/ledger/rippleState.ts b/src/models/ledger/rippleState.ts index 9a1d804c..f422e9be 100644 --- a/src/models/ledger/rippleState.ts +++ b/src/models/ledger/rippleState.ts @@ -2,19 +2,74 @@ import { IssuedCurrencyAmount } from '../common' import BaseLedgerEntry from './baseLedgerEntry' +/** + * The RippleState object type connects two accounts in a single currency. + * + * @category Ledger Entries + */ export default interface RippleState extends BaseLedgerEntry { LedgerEntryType: 'RippleState' + /** A bit-map of boolean options enabled for this object. */ Flags: number + /** + * The balance of the trust line, from the perspective of the low account. A + * negative balance indicates that the low account has issued currency to the + * high account. The issuer is always the neutral value ACCOUNT_ONE. + */ Balance: IssuedCurrencyAmount + /** + * The limit that the low account has set on the trust line. The issuer is + * the address of the low account that set this limit. + */ LowLimit: IssuedCurrencyAmount + /** + * The limit that the high account has set on the trust line. The issuer is + * the address of the high account that set this limit. + */ HighLimit: IssuedCurrencyAmount + /** + * The identifying hash of the transaction that most recently modified this + * object. + */ PreviousTxnID: string + /** + * The index of the ledger that contains the transaction that most recently + * modified this object. + */ PreviousTxnLgrSeq: number + /** + * A hint indicating which page of the low account's owner directory links to + * this object, in case the directory consists of multiple pages. + */ LowNode?: string + /** + * A hint indicating which page of the high account's owner directory links + * to this object, in case the directory consists of multiple pages. + */ HighNode?: string + /** + * The inbound quality set by the low account, as an integer in the implied + * ratio LowQualityIn:1,000,000,000. As a special case, the value 0 is + * equivalent to 1 billion, or face value. + */ LowQualityIn?: number + /** + * The outbound quality set by the low account, as an integer in the implied + * ratio LowQualityOut:1,000,000,000. As a special case, the value 0 is + * equivalent to 1 billion, or face value. + */ LowQualityOut?: number + /** + * The inbound quality set by the high account, as an integer in the implied + * ratio HighQualityIn:1,000,000,000. As a special case, the value 0 is + * equivalent to 1 billion, or face value. + */ HighQualityIn?: number + /** + * The outbound quality set by the high account, as an integer in the implied + * ratio HighQualityOut:1,000,000,000. As a special case, the value 0 is + * equivalent to 1 billion, or face value. + */ HighQualityOut?: number } diff --git a/src/models/ledger/signerList.ts b/src/models/ledger/signerList.ts index 08228b39..95d30b0c 100644 --- a/src/models/ledger/signerList.ts +++ b/src/models/ledger/signerList.ts @@ -7,14 +7,51 @@ interface SignerEntry { } } +/** + * The SignerList object type represents a list of parties that, as a group, + * are authorized to sign a transaction in place of an individual account. You + * can create, replace, or remove a signer list using a SignerListSet + * transaction. + * + * @category Ledger Entries + */ export default interface SignerList extends BaseLedgerEntry { LedgerEntryType: 'SignerList' + /** + * A bit-map of Boolean flags enabled for this signer list. For more + * information, see SignerList Flags. + */ Flags: number + /** + * The identifying hash of the transaction that most recently modified this + * object. + */ PreviousTxnID: string + /** + * The index of the ledger that contains the transaction that most recently + * modified this object. + */ PreviousTxnLgrSeq: number + /** + * A hint indicating which page of the owner directory links to this object, + * in case the directory consists of multiple pages. + */ OwnerNode: string + /** + * An array of Signer Entry objects representing the parties who are part of + * this signer list. + */ SignerEntries: SignerEntry[] + /** + * An ID for this signer list. Currently always set to 0. If a future + * amendment allows multiple signer lists for an account, this may change. + */ SignerListID: number + /** + * A target number for signer weights. To produce a valid signature for the + * owner of this SignerList, the signers must provide valid signatures whose + * weights sum to this value or more. + */ SignerQuorum: number } diff --git a/src/models/ledger/ticket.ts b/src/models/ledger/ticket.ts index d831f0b8..e554e8c3 100644 --- a/src/models/ledger/ticket.ts +++ b/src/models/ledger/ticket.ts @@ -1,11 +1,36 @@ import BaseLedgerEntry from './baseLedgerEntry' +/** + * The Ticket object type represents a Ticket, which tracks an account sequence + * number that has been set aside for future use. You can create new tickets + * with a TicketCreate transaction. + * + * @category Ledger Entries + */ export default interface Ticket extends BaseLedgerEntry { LedgerEntryType: 'Ticket' + /** The account that owns this Ticket. */ Account: string + /** + * A bit-map of Boolean flags enabled for this Ticket. Currently, there are + * no flags defined for Tickets. + */ Flags: number + /** + * A hint indicating which page of the owner directory links to this object, + * in case the directory consists of multiple pages. + */ OwnerNode: string + /** + * The identifying hash of the transaction that most recently modified this + * object. + */ PreviousTxnID: string + /** + * The index of the ledger that contains the transaction that most recently + * modified this object. + */ PreviousTxnLgrSeq: number + /** The Sequence Number this Ticket sets aside. */ TicketSequence: number } diff --git a/src/models/methods/accountChannels.ts b/src/models/methods/accountChannels.ts index f3d805d0..ad2c51af 100644 --- a/src/models/methods/accountChannels.ts +++ b/src/models/methods/accountChannels.ts @@ -17,24 +17,84 @@ interface Channel { destination_tag?: number } +/** + * The account_channels method returns information about an account's Payment + * Channels. This includes only channels where the specified account is the + * channel's source, not the destination. (A channel's "source" and "owner" are + * the same.) All information retrieved is relative to a particular version of + * the ledger. Returns an {@link AccountChannelsResponse}. + * + * @category Requests + */ export interface AccountChannelsRequest extends BaseRequest { command: 'account_channels' + /** + * The unique identifier of an account, typically the account's address. The + * request returns channels where this account is the channel's owner/source. + * + */ account: string + /** + * The unique identifier of an account, typically the account's address. If + * provided, filter results to payment channels whose destination is this + * account. + */ destination_account?: string + /** 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex + /** + * Limit the number of transactions to retrieve. Cannot be less than 10 or + * more than 400. The default is 200. + */ limit?: number + /** + * Value from a previous paginated response. Resume retrieving data where + * that response left off. + */ marker?: unknown } +/** + * The expected response from an {@link AccountChannelsRequest}. + * + * @category Responses + */ export interface AccountChannelsResponse extends BaseResponse { result: { + /** + * The address of the source/owner of the payment channels. This + * corresponds to the account field of the request. + */ account: string + /** Payment channels owned by this account. */ channels: Channel[] + /** + * The identifying hash of the ledger version used to generate this + * response. + */ ledger_hash: string + /** The ledger index of the ledger version used to generate this response. */ ledger_index: number + /** + * If true, the information in this response comes from a validated ledger + * version. Otherwise, the information is subject to change. + */ validated?: boolean + /** + * The limit to how many channel objects were actually returned by this + * request. + */ limit?: number + /** + * Server-defined value for pagination. Pass this to the next call to + * resume getting results where this call left off. Omitted when there are + * no additional pages after this one. + */ marker?: unknown } } diff --git a/src/models/methods/accountCurrencies.ts b/src/models/methods/accountCurrencies.ts index 665e8218..f0df11b3 100644 --- a/src/models/methods/accountCurrencies.ts +++ b/src/models/methods/accountCurrencies.ts @@ -2,21 +2,51 @@ import { LedgerIndex } from '../common' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `account_currencies` command retrieves a list of currencies that an + * account can send or receive, based on its trust lines. Expects an + * {@link AccountCurrenciesResponse}. + * + * @category Requests + */ export interface AccountCurrenciesRequest extends BaseRequest { command: 'account_currencies' + /** A unique identifier for the account, most commonly the account's address. */ account: string - destination_account?: string + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex + /** + * If true, then the account field only accepts a public key or XRP Ledger + * address. Otherwise, account can be a secret or passphrase (not + * recommended). The default is false. + */ strict?: boolean } +/** + * The expected response from an {@link AccountCurrenciesRequest}. + * + * @category Responses + */ export interface AccountCurrenciesResponse extends BaseResponse { result: { + /** + * The identifying hash of the ledger version used to retrieve this data, + * as hex. + */ ledger_hash?: string + /** The ledger index of the ledger version used to retrieve this data. */ ledger_index: number + /** Array of Currency Codes for currencies that this account can receive. */ receive_currencies: string[] + /** Array of Currency Codes for currencies that this account can send. */ send_currencies: string[] + /** If true, this data comes from a validated ledger. */ validated: boolean } } diff --git a/src/models/methods/accountInfo.ts b/src/models/methods/accountInfo.ts index 553b545c..3024a5d5 100644 --- a/src/models/methods/accountInfo.ts +++ b/src/models/methods/accountInfo.ts @@ -3,40 +3,125 @@ import { AccountRoot, SignerList } from '../ledger' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `account_info` command retrieves information about an account, its + * activity, and its XRP balance. All information retrieved is relative to a + * particular version of the ledger. Returns an {@link AccountInfoResponse}. + * + * @category Requests + */ export interface AccountInfoRequest extends BaseRequest { command: 'account_info' + /** A unique identifier for the account, most commonly the account's address. */ account: string + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex + /** + * Whether to get info about this account's queued transactions. Can only be + * used when querying for the data from the current open ledger. Not available + * from servers in Reporting Mode. + */ queue?: boolean + /** + * Request SignerList objects associated with this account. + */ signer_lists?: boolean + /** + * If true, then the account field only accepts a public key or XRP Ledger + * address. Otherwise, account can be a secret or passphrase (not + * recommended). The default is false. + */ strict?: boolean } interface QueueTransaction { + /** + * Whether this transaction changes this address's ways of authorizing + * transactions. + */ auth_change: boolean + /** The Transaction Cost of this transaction, in drops of XRP. */ fee: string + /** + * The transaction cost of this transaction, relative to the minimum cost for + * this type of transaction, in fee levels. + */ fee_level: string + /** The maximum amount of XRP, in drops, this transaction could send or destroy. */ max_spend_drops: string + /** The Sequence Number of this transaction. */ seq: number } interface QueueData { + /** Number of queued transactions from this address. */ txn_count: number + /** + * Whether a transaction in the queue changes this address's ways of + * authorizing transactions. If true, this address can queue no further + * transactions until that transaction has been executed or dropped from the + * queue. + */ auth_change_queued?: boolean + /** The lowest Sequence Number among transactions queued by this address. */ lowest_sequence?: number + /** The highest Sequence Number among transactions queued by this address. */ highest_sequence?: number + /** + * Integer amount of drops of XRP that could be debited from this address if + * every transaction in the queue consumes the maximum amount of XRP possible. + */ max_spend_drops_total?: string + /** Information about each queued transaction from this address. */ transactions?: QueueTransaction[] } +/** + * Response expected from an {@link AccountInfoRequest}. + * + * @category Responses + */ export interface AccountInfoResponse extends BaseResponse { result: { + /** + * The AccountRoot ledger object with this account's information, as stored + * in the ledger. + */ account_data: AccountRoot + /** + * Array of SignerList ledger objects associated with this account for + * Multi-Signing. Since an account can own at most one SignerList, this + * array must have exactly one member if it is present. + */ signer_lists?: SignerList[] + /** + * The ledger index of the current in-progress ledger, which was used when + * retrieving this information. + */ ledger_current_index?: number + /** + * The ledger index of the ledger version used when retrieving this + * information. The information does not contain any changes from ledger + * versions newer than this one. + */ ledger_index?: number + /** + * Information about queued transactions sent by this account. This + * information describes the state of the local rippled server, which may be + * different from other servers in the peer-to-peer XRP Ledger network. Some + * fields may be omitted because the values are calculated "lazily" by the + * queuing mechanism. + */ queue_data?: QueueData + /** + * True if this data is from a validated ledger version; if omitted or set + * to false, this data is not final. + */ validated?: boolean } } diff --git a/src/models/methods/accountLines.ts b/src/models/methods/accountLines.ts index e8e41562..fb2e3c71 100644 --- a/src/models/methods/accountLines.ts +++ b/src/models/methods/accountLines.ts @@ -3,38 +3,142 @@ import { LedgerIndex } from '../common' import { BaseRequest, BaseResponse } from './baseMethod' export interface Trustline { + /** The unique Address of the counterparty to this trust line. */ account: string + /** + * Representation of the numeric balance currently held against this line. A + * positive balance means that the perspective account holds value; a negative + * Balance means that the perspective account owes value. + */ balance: string + /** A Currency Code identifying what currency this trust line can hold. */ currency: string + /** + * The maximum amount of the given currency that this account is willing to + * owe the peer account. + */ limit: string + /** + * The maximum amount of currency that the issuer account is willing to owe + * the perspective account. + */ limit_peer: string + /** + * Rate at which the account values incoming balances on this trust line, as + * a ratio of this value per 1 billion units. (For example, a value of 500 + * million represents a 0.5:1 ratio.) As a special case, 0 is treated as a + * 1:1 ratio. + */ quality_in: number + /** + * Rate at which the account values outgoing balances on this trust line, as + * a ratio of this value per 1 billion units. (For example, a value of 500 + * million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 + * ratio. + */ quality_out: number + /** + * If true, this account has enabled the No Ripple flag for this trust line. + * If present and false, this account has disabled the No Ripple flag, but, + * because the account also has the Default Ripple flag enabled, that is not + * considered the default state. If omitted, the account has the No Ripple + * flag disabled for this trust line and Default Ripple disabled. + */ no_ripple?: boolean + /** + * If true, the peer account has enabled the No Ripple flag for this trust + * line. If present and false, this account has disabled the No Ripple flag, + * but, because the account also has the Default Ripple flag enabled, that is + * not considered the default state. If omitted, the account has the No Ripple + * flag disabled for this trust line and Default Ripple disabled. + */ no_ripple_peer?: boolean + /** If true, this account has authorized this trust line. The default is false. */ authorized?: boolean + /** If true, the peer account has authorized this trust line. The default is false. */ peer_authorized?: boolean + /** If true, this account has frozen this trust line. The default is false. */ freeze?: boolean + /** + * If true, the peer account has frozen this trust line. The default is + * false. + */ freeze_peer?: boolean } +/** + * The account_lines method returns information about an account's trust lines, + * including balances in all non-XRP currencies and assets. All information + * retrieved is relative to a particular version of the ledger. Expects an + * {@link AccountLinesResponse}. + * + * @category Requests + */ export interface AccountLinesRequest extends BaseRequest { command: 'account_lines' + /** A unique identifier for the account, most commonly the account's Address. */ account: string + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex + /** + * The Address of a second account. If provided, show only lines of trust + * connecting the two accounts. + */ peer?: string + /** + * Limit the number of trust lines to retrieve. The server is not required to + * honor this value. Must be within the inclusive range 10 to 400. + */ limit?: number + /** + * Value from a previous paginated response. Resume retrieving data where + * that response left off. + */ marker?: unknown } +/** + * Response expected from an {@link AccountLinesRequest}. + * + * @category Responses + */ export interface AccountLinesResponse extends BaseResponse { result: { + /** + * Unique Address of the account this request corresponds to. This is the + * "perspective account" for purpose of the trust lines. + */ account: string + /** + * Array of trust line objects. If the number of trust lines is large, only + * returns up to the limit at a time. + */ lines: Trustline[] + /** + * The ledger index of the current open ledger, which was used when + * retrieving this information. + */ ledger_current_index?: number + /** + * The ledger index of the ledger version that was used when retrieving + * this data. + */ ledger_index?: number + /** + * The identifying hash the ledger version that was used when retrieving + * this data. + */ ledger_hash?: string + /** + * Server-defined value indicating the response is paginated. Pass this to + * the next call to resume where this call left off. Omitted when there are + * No additional pages after this one. + */ marker?: unknown } } diff --git a/src/models/methods/accountObjects.ts b/src/models/methods/accountObjects.ts index 66af3773..45550b53 100644 --- a/src/models/methods/accountObjects.ts +++ b/src/models/methods/accountObjects.ts @@ -12,17 +12,52 @@ import { import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The account_objects command returns the raw ledger format for all objects + * owned by an account. For a higher-level view of an account's trust lines and + * balances, see the account_lines method instead. Expects a response in the + * form of an {@link AccountObjectsResponse}. + * + * @category Requests + */ export interface AccountObjectsRequest extends BaseRequest { command: 'account_objects' + /** A unique identifier for the account, most commonly the account's address. */ account: string + /** + * If included, filter results to include only this type of ledger object. + * The valid types are: Check , DepositPreauth, Escrow, Offer, PayChannel, + * SignerList, Ticket, and RippleState (trust line). + */ type?: AccountObjectType + /** + * If true, the response only includes objects that would block this account + * from being deleted. The default is false. + */ deletion_blockers_only?: boolean + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * Ledger automatically. + */ ledger_index?: LedgerIndex + /** + * The maximum number of objects to include in the results. Must be within + * the inclusive range 10 to 400 on non-admin connections. The default is 200. + */ limit?: number + /** + * Value from a previous paginated response. Resume retrieving data where + * that response left off. + */ marker?: unknown } +/** + * Account Objects can be a Check, a DepositPreauth, an Escrow, an Offer, a + * PayChannel, a SignerList, a Ticket, or a RippleState. + */ type AccountObject = | Check | DepositPreauth @@ -33,15 +68,48 @@ type AccountObject = | Ticket | RippleState +/** + * Response expected from an {@link AccountObjectsRequest}. + * + * @category Responses + */ export interface AccountObjectsResponse extends BaseResponse { result: { + /** Unique Address of the account this request corresponds to. */ account: string + /** + * Array of objects owned by this account. Each object is in its raw + * ledger format. + */ account_objects: AccountObject[] + /** + * The identifying hash of the ledger that was used to generate this + * response. + */ ledger_hash?: string + /** + * The ledger index of the ledger version that was used to generate this + * response. + */ ledger_index?: number + /** + * The ledger index of the current in-progress ledger version, which was + * used to generate this response. + */ ledger_current_index?: number + /** The limit that was used in this request, if any. */ limit?: number + /** + * Server-defined value indicating the response is paginated. Pass this to + * the next call to resume where this call left off. Omitted when there are + * no additional pages after this one. + */ marker?: string + /** + * If included and set to true, the information in this response comes from + * a validated ledger version. Otherwise, the information is subject to + * change. + */ validated?: boolean } } diff --git a/src/models/methods/accountOffers.ts b/src/models/methods/accountOffers.ts index f40d9cdb..b6e47b6f 100644 --- a/src/models/methods/accountOffers.ts +++ b/src/models/methods/accountOffers.ts @@ -2,32 +2,104 @@ import { Amount, LedgerIndex } from '../common' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The account_offers method retrieves a list of offers made by a given account + * that are outstanding as of a particular ledger version. Expects a response in + * the form of a {@link AccountOffersResponse}. + * + * @category Requests + */ export interface AccountOffersRequest extends BaseRequest { command: 'account_offers' + /** A unique identifier for the account, most commonly the account's Address. */ account: string + /** A 20-byte hex string identifying the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or "current", "closed", or + * "validated" to select a ledger dynamically. + */ ledger_index?: LedgerIndex + /** + * Limit the number of transactions to retrieve. The server is not required + * to honor this value. Must be within the inclusive range 10 to 400. + */ limit?: number + /** + * Value from a previous paginated response. Resume retrieving data where + * that response left off. + */ marker?: unknown + /** + * If true, then the account field only accepts a public key or XRP Ledger + * address. Otherwise, account can be a secret or passphrase (not + * recommended). The default is false. + */ strict?: boolean } interface AccountOffer { + /** Options set for this offer entry as bit-flags. */ flags: number + /** Sequence number of the transaction that created this entry. */ seq: number + /** + * The amount the account placing this Offer receives. + */ taker_gets: Amount + /** + * The amount the account placing this Offer pays. + */ taker_pays: Amount + /** + * The exchange rate of the Offer, as the ratio of the original taker_pays + * divided by the original taker_gets. When executing offers, the offer with + * the most favorable (lowest) quality is consumed first; offers with the same + * quality are executed from oldest to newest. + */ quality: string + /** + * A time after which this offer is considered unfunded, as the number of + * seconds since the Ripple Epoch. See also: Offer Expiration. + */ expiration?: number } +/** + * Response expected from an {@link AccountOffersRequest}. + * + * @category Responses + */ export interface AccountOffersResponse extends BaseResponse { result: { + /** Unique Address identifying the account that made the offers. */ account: string + /** + * Array of objects, where each object represents an offer made by this + * account that is outstanding as of the requested ledger version. If the + * number of offers is large, only returns up to limit at a time. + */ offers?: AccountOffer[] + /** + * The ledger index of the current in-progress ledger version, which was + * used when retrieving this data. + */ ledger_current_index?: number + /** + * The ledger index of the ledger version that was used when retrieving + * this data, as requested. + */ ledger_index?: number + /** + * The identifying hash of the ledger version that was used when retrieving + * this data. + */ ledger_hash?: string + /** + * Server-defined value indicating the response is paginated. Pass this to + * the next call to resume where this call left off. Omitted when there are + * no pages of information after this one. + */ marker?: unknown } } diff --git a/src/models/methods/accountTx.ts b/src/models/methods/accountTx.ts index 1827c563..5d87c9d9 100644 --- a/src/models/methods/accountTx.ts +++ b/src/models/methods/accountTx.ts @@ -4,35 +4,111 @@ import Metadata from '../transactions/metadata' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The account_tx method retrieves a list of transactions that involved the + * specified account. Expects a response in the form of a {@link + * AccountTxResponse}. + * + * @category Requests + */ export interface AccountTxRequest extends BaseRequest { command: 'account_tx' + /** A unique identifier for the account, most commonly the account's address. */ account: string + /** + * Use to specify the earliest ledger to include transactions from. A value + * of -1 instructs the server to use the earliest validated ledger version + * available. + */ ledger_index_min?: number + /** + * Use to specify the most recent ledger to include transactions from. A + * value of -1 instructs the server to use the most recent validated ledger + * version available. + */ ledger_index_max?: number + /** Use to look for transactions from a single ledger only. */ ledger_hash?: string + /** Use to look for transactions from a single ledger only. */ ledger_index?: LedgerIndex + /** + * If true, return transactions as hex strings instead of JSON. The default is + * false. + */ binary?: boolean + /** + * If true, returns values indexed with the oldest ledger first. Otherwise, + * the results are indexed with the newest ledger first. + */ forward?: boolean + /** + * Default varies. Limit the number of transactions to retrieve. The server + * is not required to honor this value. + */ limit?: number + /** + * Value from a previous paginated response. Resume retrieving data where + * that response left off. This value is stable even if there is a change in + * the server's range of available ledgers. + */ marker?: unknown } interface AccountTransaction { + /** The ledger index of the ledger version that included this transaction. */ ledger_index: number + /** + * If binary is True, then this is a hex string of the transaction metadata. + * Otherwise, the transaction metadata is included in JSON format. + */ meta: string | Metadata + /** JSON object defining the transaction. */ tx?: Transaction + /** Unique hashed String representing the transaction. */ tx_blob?: string + /** + * Whether or not the transaction is included in a validated ledger. Any + * transaction not yet in a validated ledger is subject to change. + */ validated: boolean } +/** + * Expected response from an {@link AccountTxRequest}. + * + * @category Responses + */ export interface AccountTxResponse extends BaseResponse { result: { + /** Unique Address identifying the related account. */ account: string + /** + * The ledger index of the earliest ledger actually searched for + * transactions. + */ ledger_index_min: number + /** + * The ledger index of the most recent ledger actually searched for + * transactions. + */ ledger_index_max: number + /** The limit value used in the request. */ limit: number + /** + * Server-defined value indicating the response is paginated. Pass this + * to the next call to resume where this call left off. + */ marker?: unknown + /** + * Array of transactions matching the request's criteria, as explained + * below. + */ transactions: AccountTransaction[] + /** + * If included and set to true, the information in this response comes from + * a validated ledger version. Otherwise, the information is subject to + * change. + */ validated?: boolean } } diff --git a/src/models/methods/baseMethod.ts b/src/models/methods/baseMethod.ts index a7c37486..a909eb86 100644 --- a/src/models/methods/baseMethod.ts +++ b/src/models/methods/baseMethod.ts @@ -2,8 +2,15 @@ import type { Request } from '.' export interface BaseRequest { [x: string]: unknown + /** + * A unique value to identify this request. The response to this request uses + * the same id field. This way, even if responses arrive out of order, you + * know which request prompted which response. + */ id?: number | string + /** The name of the API method. */ command: string + /** The API version to use. If omitted, use version 1. */ api_version?: number } @@ -24,6 +31,12 @@ export interface BaseResponse { api_version?: number } +/** + * The shape of an error response from rippled. xrpl.js handles rejections by + * throwing, and allowing the user to handle in the catch block of a promise. + * + * @category Responses + */ export interface ErrorResponse { id: number | string status: 'error' diff --git a/src/models/methods/bookOffers.ts b/src/models/methods/bookOffers.ts index 11743610..7726c97f 100644 --- a/src/models/methods/bookOffers.ts +++ b/src/models/methods/bookOffers.ts @@ -8,28 +8,95 @@ export interface TakerAmount { issuer?: string } +/** + * The book_offers method retrieves a list of offers, also known as the order. + * Book, between two currencies. Returns an {@link BookOffersResponse}. + * + * @category Requests + */ export interface BookOffersRequest extends BaseRequest { command: 'book_offers' + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex + /** + * If provided, the server does not provide more than this many offers in the + * results. The total number of results returned may be fewer than the limit, + * because the server omits unfunded offers. + */ limit?: number + /** + * The Address of an account to use as a perspective. Unfunded offers placed + * by this account are always included in the response. + */ taker?: string + /** + * Specification of which currency the account taking the offer would + * receive, as an object with currency and issuer fields (omit issuer for + * XRP), like currency amounts. + */ taker_gets: TakerAmount + /** + * Specification of which currency the account taking the offer would pay, as + * an object with currency and issuer fields (omit issuer for XRP), like + * currency amounts. + */ taker_pays: TakerAmount } export interface BookOffer extends Offer { + /** + * Amount of the TakerGets currency the side placing the offer has available + * to be traded. (XRP is represented as drops; any other currency is + * represented as a decimal value.) If a trader has multiple offers in the + * same book, only the highest-ranked offer includes this field. + */ owner_funds?: string + /** + * The maximum amount of currency that the taker can get, given the funding + * status of the offer. + */ taker_gets_funded?: Amount + /** + * The maximum amount of currency that the taker would pay, given the funding + * status of the offer. + */ taker_pays_funded?: Amount + /** + * The exchange rate, as the ratio taker_pays divided by taker_gets. For + * fairness, offers that have the same quality are automatically taken + * first-in, first-out. + */ quality?: string } +/** + * Expected response from a {@link BookOffersRequest}. + * + * @category Responses + */ export interface BookOffersResponse extends BaseResponse { result: { + /** + * The ledger index of the current in-progress ledger version, which was + * used to retrieve this information. + */ ledger_current_index?: number + /** + * The ledger index of the ledger version that was used when retrieving + * this data, as requested. + */ ledger_index?: number + /** + * The identifying hash of the ledger version that was used when retrieving + * this data, as requested. + */ ledger_hash?: string + /** Array of offer objects, each of which has the fields of an Offer object. */ offers: BookOffer[] validated?: boolean } diff --git a/src/models/methods/channelVerify.ts b/src/models/methods/channelVerify.ts index bd6861f8..0a53c544 100644 --- a/src/models/methods/channelVerify.ts +++ b/src/models/methods/channelVerify.ts @@ -1,15 +1,41 @@ import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `channel_verify` method checks the validity of a signature that can be + * used to redeem a specific amount of XRP from a payment channel. Expects a + * response in the form of a {@link ChannelVerifyResponse}. + * + * @category Requests + */ export interface ChannelVerifyRequest extends BaseRequest { command: 'channel_verify' + /** The amount of XRP, in drops, the provided signature authorizes. */ amount: string + /** + * The Channel ID of the channel that provides the XRP. This is a + * 64-character hexadecimal string. + */ channel_id: string + /** + * The public key of the channel and the key pair that was used to create the + * signature, in hexadecimal or the XRP Ledger's base58 format. + */ public_key: string + /** The signature to verify, in hexadecimal. */ signature: string } +/** + * Response expected from an {@link ChannelVerifyRequest}. + * + * @category Responses + */ export interface ChannelVerifyResponse extends BaseResponse { result: { + /** + * If true, the signature is valid for the stated amount, channel, and + * public key. + */ signature_verified: boolean } } diff --git a/src/models/methods/depositAuthorized.ts b/src/models/methods/depositAuthorized.ts index b10545e8..9e794221 100644 --- a/src/models/methods/depositAuthorized.ts +++ b/src/models/methods/depositAuthorized.ts @@ -2,22 +2,62 @@ import { LedgerIndex } from '../common' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The deposit_authorized command indicates whether one account is authorized to + * send payments directly to another. Expects a response in the form of a {@link + * DepositAuthorizedResponse}. + * + * @category Requests + */ export interface DepositAuthorizedRequest extends BaseRequest { command: 'deposit_authorized' + /** The sender of a possible payment. */ source_account: string + /** The recipient of a possible payment. */ destination_account: string + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex } +/** + * Expected response from a {@link DepositAuthorizedRequest}. + * + * @category Responses + */ export interface DepositAuthorizedResponse extends BaseResponse { result: { + /** + * Whether the specified source account is authorized to send payments + * directly to the destination account. If true, either the destination + * account does not require Deposit Authorization or the source account is + * preauthorized. + */ deposit_authorized: boolean + /** The destination account specified in the request. */ destination_account: string + /** + * The identifying hash of the ledger that was used to generate this + * Response. + */ ledger_hash?: string + /** + * The ledger index of the ledger version that was used to generate this + * Response. + */ ledger_index?: number + /** + * The ledger index of the current in-progress ledger version, which was + * used to generate this response. + */ ledger_current_index?: number + /** The source account specified in the request. */ source_account: string + /** If true, the information comes from a validated ledger version. */ validated?: boolean } } diff --git a/src/models/methods/fee.ts b/src/models/methods/fee.ts index efca04dd..c2582782 100644 --- a/src/models/methods/fee.ts +++ b/src/models/methods/fee.ts @@ -1,27 +1,91 @@ import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `fee` command reports the current state of the open-ledger requirements + * for the transaction cost. This requires the FeeEscalation amendment to be + * enabled. Expects a response in the form of a {@link FeeResponse}. + * + * @example + * ```ts + * const feeRequest: FeeRequest = { + * command: 'fee' + * } + * ``` + * + * @category Requests + */ export interface FeeRequest extends BaseRequest { command: 'fee' } +/** + * Response expected from a {@link FeeRequest}. + * + * @category Responses + */ export interface FeeResponse extends BaseResponse { result: { + /** Number of transactions provisionally included in the in-progress ledger. */ current_ledger_size: string + /** Number of transactions currently queued for the next ledger. */ current_queue_size: string drops: { + /** + * The transaction cost required for a reference transaction to be + * included in a ledger under minimum load, represented in drops of XRP. + */ base_fee: string + /** + * An approximation of the median transaction cost among transactions. + * Included in the previous validated ledger, represented in drops of XRP. + */ median_fee: string + /** + * The minimum transaction cost for a reference transaction to be queued + * for a later ledger, represented in drops of XRP. If greater than + * base_fee, the transaction queue is full. + */ minimum_fee: string + /** + * The minimum transaction cost that a reference transaction must pay to + * be included in the current open ledger, represented in drops of XRP. + */ open_ledger_fee: string } + /** + * The approximate number of transactions expected to be included in the + * current ledger. This is based on the number of transactions in the + * previous ledger. + */ expected_ledger_size: string + /** The Ledger Index of the current open ledger these stats describe. */ ledger_current_index: number levels: { + /** + * The median transaction cost among transactions in the previous + * validated ledger, represented in fee levels. + */ median_level: string + /** + * The minimum transaction cost required to be queued for a future + * ledger, represented in fee levels. + */ minimum_level: string + /** + * The minimum transaction cost required to be included in the current + * open ledger, represented in fee levels. + */ open_ledger_level: string + /** + * The equivalent of the minimum transaction cost, represented in fee + * levels. + */ reference_level: string } + /** + * The maximum number of transactions that the transaction queue can + * currently hold. + */ max_queue_size: string } } diff --git a/src/models/methods/gatewayBalances.ts b/src/models/methods/gatewayBalances.ts index a84363c7..a150a408 100644 --- a/src/models/methods/gatewayBalances.ts +++ b/src/models/methods/gatewayBalances.ts @@ -2,12 +2,45 @@ import { LedgerIndex } from '../common' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The gateway_balances command calculates the total balances issued by a given + * account, optionally excluding amounts held by operational addresses. Expects + * a response in the form of a {@link GatewayBalancesResponse}. + * + * @example + * ```ts + * const gatewayBalances: GatewayBalanceRequest = { + * "id": "example_gateway_balances_1", + * "command": "gateway_balances", + * "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", + * "strict": true, + * "hotwallet": ["rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ","ra7JkEzrgeKHdzKgo4EUUVBnxggY4z37kt"], + * "ledger_index": "validated" + * } + * ``` + * + * @category Requests + */ export interface GatewayBalancesRequest extends BaseRequest { command: 'gateway_balances' + /** The Address to check. This should be the issuing address. */ account: string + /** + * If true, only accept an address or public key for the account parameter. + * Defaults to false. + */ strict?: boolean + /** + * An operational address to exclude from the balances issued, or an array of + * Such addresses. + */ hotwallet?: string | string[] + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger version to use, or a shortcut string to + * choose a ledger automatically. + */ ledger_index?: LedgerIndex } @@ -16,14 +49,44 @@ interface Balance { value: string } +/** + * Expected response from a {@link GatewayBalancesRequest}. + * + * @category Responses + */ export interface GatewayBalancesResponse extends BaseResponse { result: { + /** The address of the account that issued the balances. */ account: string + /** + * Total amounts issued to addresses not excluded, as a map of currencies + * to the total value issued. + */ obligations?: { [currency: string]: string } + /** + * Amounts issued to the hotwallet addresses from the request. The keys are + * addresses and the values are arrays of currency amounts they hold. + */ balances?: { [address: string]: Balance[] } + /** + * Total amounts held that are issued by others. In the recommended + * configuration, the issuing address should have none. + */ assets?: { [address: string]: Balance[] } + /** + * The identifying hash of the ledger version that was used to generate + * this response. + */ ledger_hash?: string + /** + * The ledger index of the ledger version that was used to generate this + * response. + */ ledger_current_index?: number + /** + * The ledger index of the current in-progress ledger version, which was + * used to retrieve this information. + */ ledger_index?: number } } diff --git a/src/models/methods/index.ts b/src/models/methods/index.ts index 59594158..26fac8f0 100644 --- a/src/models/methods/index.ts +++ b/src/models/methods/index.ts @@ -60,7 +60,9 @@ import { import { TxRequest, TxResponse } from './tx' import { UnsubscribeRequest, UnsubscribeResponse } from './unsubscribe' -// account methods +/** + * @category Requests + */ type Request = | AccountChannelsRequest | AccountCurrenciesRequest @@ -101,7 +103,9 @@ type Request = | PingRequest | RandomRequest -// account methods +/** + * @category Responses + */ type Response = | AccountChannelsResponse | AccountCurrenciesResponse diff --git a/src/models/methods/ledger.ts b/src/models/methods/ledger.ts index 2af7a363..34a68cc1 100644 --- a/src/models/methods/ledger.ts +++ b/src/models/methods/ledger.ts @@ -5,16 +5,73 @@ import TransactionMetadata from '../transactions/metadata' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * Retrieve information about the public ledger. Expects a response in the form + * of a {@link LedgerResponse}. + * + * @example + * ```ts + * const ledger: LedgerRequest = { + * "id": 14, + * "command": "ledger", + * "ledger_index": "validated", + * "full": false, + * "accounts": false, + * "transactions": false, + * "expand": false, + * "owner_funds": false + * } + * ``` + * + * @category Requests + */ export interface LedgerRequest extends BaseRequest { command: 'ledger' + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex + /** + * Admin required If true, return full information on the entire ledger. + * Ignored if you did not specify a ledger version. Defaults to false. + */ full?: boolean + /** + * Admin required. If true, return information on accounts in the ledger. + * Ignored if you did not specify a ledger version. Defaults to false. + */ accounts?: boolean + /** + * If true, return information on transactions in the specified ledger + * version. Defaults to false. Ignored if you did not specify a ledger + * version. + */ transactions?: boolean + /** + * Provide full JSON-formatted information for transaction/account + * information instead of only hashes. Defaults to false. Ignored unless you + * request transactions, accounts, or both. + */ expand?: boolean + /** + * If true, include owner_funds field in the metadata of OfferCreate + * transactions in the response. Defaults to false. Ignored unless + * transactions are included and expand is true. + */ owner_funds?: boolean + /** + * If true, and transactions and expand are both also true, return + * transaction information in binary format (hexadecimal string) instead of + * JSON format. + */ binary?: boolean + /** + * If true, and the command is requesting the current ledger, includes an + * array of queued transactions in the results. + */ queue?: boolean } @@ -48,12 +105,30 @@ interface BinaryLedger transactions?: string[] } +/** + * Response expected from a {@link LedgerRequest}. + * + * @category Responses + */ export interface LedgerResponse extends BaseResponse { result: { + /** The complete header data of this {@link Ledger}. */ ledger: Ledger | BinaryLedger + /** Unique identifying hash of the entire ledger. */ ledger_hash: string + /** The Ledger Index of this ledger. */ ledger_index: number + /** + * If true, this is a validated ledger version. If omitted or set to false, + * this ledger's data is not final. + */ queue_data?: Array + /** + * Array of objects describing queued transactions, in the same order as + * the queue. If the request specified expand as true, members contain full + * representations of the transactions, in either JSON or binary depending + * on whether the request specified binary as true. + */ validated?: boolean } } diff --git a/src/models/methods/ledgerClosed.ts b/src/models/methods/ledgerClosed.ts index e33cd47e..0bde8171 100644 --- a/src/models/methods/ledgerClosed.ts +++ b/src/models/methods/ledgerClosed.ts @@ -1,9 +1,29 @@ import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The ledger_closed method returns the unique identifiers of the most recently + * closed ledger. Expects a response in the form of a {@link + * LedgerClosedResponse}. + * + * @example + * * + * ```ts + * const ledgerClosed: LedgerClosedRequest = { + * "command": "ledger_closed" + * } + * ``` + * + * @category Requests + */ export interface LedgerClosedRequest extends BaseRequest { command: 'ledger_closed' } +/** + * The response expected from a {@link LedgerClosedRequest}. + * + * @category Responses + */ export interface LedgerClosedResponse extends BaseResponse { result: { ledger_hash: string diff --git a/src/models/methods/ledgerCurrent.ts b/src/models/methods/ledgerCurrent.ts index 882ff05a..f7ba0db3 100644 --- a/src/models/methods/ledgerCurrent.ts +++ b/src/models/methods/ledgerCurrent.ts @@ -1,11 +1,31 @@ import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The ledger_current method returns the unique identifiers of the current + * in-progress ledger. Expects a response in the form of a {@link + * LedgerCurrentResponse}. + * + * @example + * ```ts + * const ledgerCurrent: LedgerCurrentRequest = { + * "command": "ledger_current" + * } + * ``` + * + * @category Requests + */ export interface LedgerCurrentRequest extends BaseRequest { command: 'ledger_current' } +/** + * Response expected from a {@link LedgerCurrentRequest}. + * + * @category Responses + */ export interface LedgerCurrentResponse extends BaseResponse { result: { + /** The ledger index of this ledger version. */ ledger_current_index: number } } diff --git a/src/models/methods/ledgerData.ts b/src/models/methods/ledgerData.ts index e569b811..7dc18ae5 100644 --- a/src/models/methods/ledgerData.ts +++ b/src/models/methods/ledgerData.ts @@ -3,12 +3,47 @@ import { LedgerEntry } from '../ledger' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `ledger_data` method retrieves contents of the specified ledger. You can + * iterate through several calls to retrieve the entire contents of a single + * ledger version. + * + * @example + * ```ts + * const ledgerData: LedgerDataRequest = { + * "id": 2, + * "ledger_hash": "842B57C1CC0613299A686D3E9F310EC0422C84D3911E5056389AA7E5808A93C8", + * "command": "ledger_data", + * "limit": 5, + * "binary": true + * } + * ``` + * + * @category Requests + */ export interface LedgerDataRequest extends BaseRequest { command: 'ledger_data' + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex + /** + * If set to true, return ledger objects as hashed hex strings instead of + * JSON. + */ binary?: boolean + /** + * Limit the number of ledger objects to retrieve. The server is not required + * to honor this value. + */ limit?: number + /** + * Value from a previous paginated response. Resume retrieving data where + * that response left off. + */ marker?: unknown } @@ -20,11 +55,26 @@ interface BinaryLedgerEntry { type State = { index: string } & (BinaryLedgerEntry | LabeledLedgerEntry) +/** + * The response expected from a {@link LedgerDataRequest}. + * + * @category Responses + */ export interface LedgerDataResponse extends BaseResponse { result: { + /** The ledger index of this ledger version. */ ledger_index: number + /** Unique identifying hash of this ledger version. */ ledger_hash: string + /** + * Array of JSON objects containing data from the ledger's state tree, + * as defined below. + */ state: State[] + /** + * Server-defined value indicating the response is paginated. Pass this to + * the next call to resume where this call left off. + */ marker?: unknown validated?: boolean } diff --git a/src/models/methods/ledgerEntry.ts b/src/models/methods/ledgerEntry.ts index a2eae952..b4203a45 100644 --- a/src/models/methods/ledgerEntry.ts +++ b/src/models/methods/ledgerEntry.ts @@ -3,70 +3,159 @@ import { LedgerEntry } from '../ledger' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `ledger_entry` method returns a single ledger object from the XRP Ledger + * in its raw format. Expects a response in the form of a {@link + * LedgerEntryResponse}. + * + * @example + * ```ts + * const ledgerEntry: LedgerEntryRequest = { + * command: "ledger_entry", + * ledger_index: 60102302, + * index: "7DB0788C020F02780A673DC74757F23823FA3014C1866E72CC4CD8B226CD6EF4" + * } + * ``` + * + * @category Requests + */ export interface LedgerEntryRequest extends BaseRequest { command: 'ledger_entry' + /** + * If true, return the requested ledger object's contents as a hex string in + * the XRP Ledger's binary format. Otherwise, return data in JSON format. The + * default is false. + */ binary?: boolean + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** The ledger index of the ledger to use, or a shortcut string. */ ledger_index?: LedgerIndex - // Only one of the following properties should be defined in a single request - // https://xrpl.org/ledger_entry.html - + /* + * Only one of the following properties should be defined in a single request + * https://xrpl.org/ledger_entry.html. + * + * Retrieve any type of ledger object by its unique ID. + */ index?: string + /** + * Retrieve an AccountRoot object by its address. This is roughly equivalent + * to the an {@link AccountInfoRequest}. + */ account_root?: string + /** + * The DirectoryNode to retrieve. If a string, must be the object ID of the + * directory, as hexadecimal. If an object, requires either `dir_root` o + * Owner as a sub-field, plus optionally a `sub_index` sub-field. + */ directory?: | { + /** If provided, jumps to a later "page" of the DirectoryNode. */ sub_index?: number + /** Unique index identifying the directory to retrieve, as a hex string. */ dir_root?: string + /** Unique address of the account associated with this directory. */ owner?: string } | string + /** + * The Offer object to retrieve. If a string, interpret as the unique object + * ID to the Offer. If an object, requires the sub-fields `account` and `seq` + * to uniquely identify the offer. + */ offer?: | { + /** The account that placed the offer. */ account: string + /** Sequence Number of the transaction that created the Offer object. */ seq: number } | string + /** + * Object specifying the RippleState (trust line) object to retrieve. The + * accounts and currency sub-fields are required to uniquely specify the + * rippleState entry to retrieve. + */ ripple_state?: { + /** + * 2-length array of account Addresses, defining the two accounts linked by + * this RippleState object. + */ accounts: string[] + /** Currency Code of the RippleState object to retrieve. */ currency: string } + /** The object ID of a Check object to retrieve. */ check?: string + /** + * The Escrow object to retrieve. If a string, must be the object ID of the + * escrow, as hexadecimal. If an object, requires owner and seq sub-fields. + */ escrow?: | { + /** The owner (sender) of the Escrow object. */ owner: string + /** Sequence Number of the transaction that created the Escrow object. */ seq: number } | string + /** The object ID of a PayChannel object to retrieve. */ payment_channel?: string + /** + * Specify a DepositPreauth object to retrieve. If a string, must be the + * object ID of the DepositPreauth object, as hexadecimal. If an object, + * requires owner and authorized sub-fields. + */ deposit_preauth?: | { + /** The account that provided the preauthorization. */ owner: string + /** The account that received the preauthorization. */ authorized: string } | string + /** + * The Ticket object to retrieve. If a string, must be the object ID of the + * Ticket, as hexadecimal. If an object, the `owner` and `ticket_sequence` + * sub-fields are required to uniquely specify the Ticket entry. + */ ticket?: | { + /** The owner of the Ticket object. */ owner: string + /** The Ticket Sequence number of the Ticket entry to retrieve. */ ticket_sequence: number } | string } +/** + * Response expected from a {@link LedgerEntryRequest}. + * + * @category Responses + */ export interface LedgerEntryResponse extends BaseResponse { result: { + /** The unique ID of this ledger object. */ index: string + /** The ledger index of the ledger that was used when retrieving this data. */ ledger_current_index: number + /** + * Object containing the data of this ledger object, according to the + * ledger format. + */ node?: LedgerEntry + /** The binary representation of the ledger object, as hexadecimal. */ node_binary?: string validated?: boolean } diff --git a/src/models/methods/manifest.ts b/src/models/methods/manifest.ts index d6df13d0..c4889a72 100644 --- a/src/models/methods/manifest.ts +++ b/src/models/methods/manifest.ts @@ -1,19 +1,54 @@ import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `manifest` method reports the current "manifest" information for a given + * validator public key. The "manifest" is the public portion of that + * validator's configured token. Expects a response in the form of a {@link + * ManifestResponse}. + * + * @example + * ```ts + * const manifest: ManifestRequest = { + * "command": "manifest", + * "public_key": "nHUFE9prPXPrHcG3SkwP1UzAQbSphqyQkQK9ATXLZsfkezhhda3p" + * } + * ``` + * + * @category Requests + */ export interface ManifestRequest extends BaseRequest { command: 'manifest' + /** + * The base58-encoded public key of the validator to look up. This can be the + * master public key or ephemeral public key. + */ public_key: string } +/** + * Response expected from a {@link ManifestRequest}. + * + * @category Responses + */ export interface ManifestResponse extends BaseResponse { result: { + /** + * The data contained in this manifest. Omitted if the server does not have + * A manifest for the public_key from the request. + */ details?: { domain: string ephemeral_key: string master_key: string seq: number } + /** + * The full manifest data in base64 format. This data is serialized to + * binary before being base64-encoded. Omitted if the server does not have a + * manifest for the public_key from the request. + */ manifest?: string + /** The public_key from the request. */ requested: string } } diff --git a/src/models/methods/norippleCheck.ts b/src/models/methods/norippleCheck.ts index 56d3ffcf..91c4e770 100644 --- a/src/models/methods/norippleCheck.ts +++ b/src/models/methods/norippleCheck.ts @@ -3,19 +3,80 @@ import { Transaction } from '../transactions' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `noripple_check` command provides a quick way to check the status of th + * default ripple field for an account and the No Ripple flag of its trust + * lines, compared with the recommended settings. Expects a response in the form + * of an {@link NoRippleCheckResponse}. + * + * @example + * ```ts + * const noRipple: NoRippleCheckRequest = { + * "id": 0, + * "command": "noripple_check", + * "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", + * "role": "gateway", + * "ledger_index": "current", + * "limit": 2, + * "transactions": true + * } + * ``` + * + * @category Requests + */ export interface NoRippleCheckRequest extends BaseRequest { command: 'noripple_check' + /** A unique identifier for the account, most commonly the account's address. */ account: string + /** + * Whether the address refers to a gateway or user. Recommendations depend on + * the role of the account. Issuers must have Default Ripple enabled and must + * disable No Ripple on all trust lines. Users should have Default Ripple + * disabled, and should enable No Ripple on all trust lines. + */ role: 'gateway' | 'user' + /** + * If true, include an array of suggested transactions, as JSON objects, + * that you can sign and submit to fix the problems. Defaults to false. + */ transactions?: boolean + /** + * The maximum number of trust line problems to include in the results. + * Defaults to 300. + */ + limit?: number + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex } +/** + * Response expected by a {@link NoRippleCheckRequest}. + * + * @category Responses + */ export interface NoRippleCheckResponse extends BaseResponse { result: { + /** The ledger index of the ledger used to calculate these results. */ ledger_current_index: number + /** + * Array of strings with human-readable descriptions of the problems. + * This includes up to one entry if the account's Default Ripple setting is + * not as recommended, plus up to limit entries for trust lines whose no + * ripple setting is not as recommended. + */ problems: string[] + /** + * If the request specified transactions as true, this is an array of JSON + * objects, each of which is the JSON form of a transaction that should fix + * one of the described problems. The length of this array is the same as + * the problems array, and each entry is intended to fix the problem + * described at the same index into that array. + */ transactions: Transaction[] } } diff --git a/src/models/methods/pathFind.ts b/src/models/methods/pathFind.ts index 60dd5928..abca7b61 100644 --- a/src/models/methods/pathFind.ts +++ b/src/models/methods/pathFind.ts @@ -7,46 +7,105 @@ interface BasePathFindRequest extends BaseRequest { subcommand: string } +/** Start sending pathfinding information. */ interface PathFindCreateRequest extends BasePathFindRequest { subcommand: 'create' + /** + * Unique address of the account to find a path from. In other words, the. + * Account that would be sending a payment. + */ source_account: string + /** Unique address of the account to find a path to. */ destination_account: string + /** + * Currency Amount that the destination account would receive in a + * transaction. + */ destination_amount: Amount + /** Currency amount that would be spent in the transaction. */ send_max?: Amount + /** + * Array of arrays of objects, representing payment paths to check. You can + * use this to keep updated on changes to particular paths you already know + * about, or to check the overall cost to make a payment along a certain path. + */ paths?: Path[] } +/** Stop sending pathfinding information. */ interface PathFindCloseRequest extends BasePathFindRequest { subcommand: 'close' } +/** Get the information of the currently-open pathfinding request. */ interface PathFindStatusRequest extends BasePathFindRequest { subcommand: 'status' } +/** + * The `path_find` method searches for a path along which a transaction can + * possibly be made, and periodically sends updates when the path changes over + * time. For a simpler version that is supported by JSON-RPC, see the + * `ripple_path_find` method. + * + * @category Requests + */ export type PathFindRequest = | PathFindCreateRequest | PathFindCloseRequest | PathFindStatusRequest interface PathOption { + /** Array of arrays of objects defining payment paths. */ paths_computed: Path[] + /** + * Currency Amount that the source would have to send along this path for the. + * Destination to receive the desired amount. + */ source_amount: Amount } +/** + * Response expected from a {@link PathFindRequest}. + * + * @category Responses + */ export interface PathFindResponse extends BaseResponse { result: { + /** + * Array of objects with suggested paths to take, as described below. If + * empty, then no paths were found connecting the source and destination + * accounts. + */ alternatives: PathOption[] + /** Unique address of the account that would receive a transaction. */ destination_account: string + /** Currency amount that the destination would receive in a transaction. */ destination_amount: Amount + /** Unique address that would send a transaction. */ source_account: string + /** + * If false, this is the result of an incomplete search. A later reply + * may have a better path. If true, then this is the best path found. (It is + * still theoretically possible that a better path could exist, but rippled + * won't find it.) Until you close the pathfinding request, rippled. + * Continues to send updates each time a new ledger closes. + */ full_reply: boolean + /** + * The ID provided in the WebSocket request is included again at this + * level. + */ id?: number | string + /** + * The value true indicates this reply is in response to a path_find close + * command. + */ closed?: true + /** + * The value true indicates this reply is in response to a `path_find` + * status command. + */ status?: true } } - -// TODO: figure out where to put the path_find asynchronous follow-ups -// https://xrpl.org/path_find.html#asynchronous-follow-ups -// probably with the subscribe response objects diff --git a/src/models/methods/ping.ts b/src/models/methods/ping.ts index 84711b44..52b760e7 100644 --- a/src/models/methods/ping.ts +++ b/src/models/methods/ping.ts @@ -1,9 +1,21 @@ import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The ping command returns an acknowledgement, so that clients can test the + * connection status and latency. Expects a response in the form of a {@link + * PingResponse}. + * + * @category Requests + */ export interface PingRequest extends BaseRequest { command: 'ping' } +/** + * Response expected from a {@link PingRequest}. + * + * @category Responses + */ export interface PingResponse extends BaseResponse { // TODO: figure out if there's a better way to type this // eslint-disable-next-line @typescript-eslint/ban-types -- actually should be an empty object diff --git a/src/models/methods/random.ts b/src/models/methods/random.ts index ae3ec141..5c659588 100644 --- a/src/models/methods/random.ts +++ b/src/models/methods/random.ts @@ -1,9 +1,21 @@ import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The random command provides a random number to be used as a source of + * entropy for random number generation by clients. Expects a response in the + * form of a {@link RandomResponse}. + * + * @category Requests + */ export interface RandomRequest extends BaseRequest { command: 'random' } +/** + * Response expected from a {@link RandomRequest}. + * + * @category Responses + */ export interface RandomResponse extends BaseResponse { result: { random: string diff --git a/src/models/methods/ripplePathFind.ts b/src/models/methods/ripplePathFind.ts index cc93c86d..c90acca8 100644 --- a/src/models/methods/ripplePathFind.ts +++ b/src/models/methods/ripplePathFind.ts @@ -7,26 +7,74 @@ interface SourceCurrencyAmount { issuer?: string } +/** + * The `ripple_path_find` method is a simplified version of the path_find method + * that provides a single response with a payment path you can use right away. + * Expects a response in the form of a {@link RipplePathFindResponse}. + * + * @category Requests + */ export interface RipplePathFindRequest extends BaseRequest { command: 'ripple_path_find' + /** Unique address of the account that would send funds in a transaction. */ source_account: string + /** Unique address of the account that would receive funds in a transaction. */ destination_account: string + /** + * Currency Amount that the destination account would receive in a + * transaction. + */ destination_amount: Amount + /** + * Currency Amount that would be spent in the transaction. Cannot be used + * with `source_currencies`. + */ send_max?: Amount + /** + * Array of currencies that the source account might want to spend. Each + * entry in the array should be a JSON object with a mandatory currency field + * and optional issuer field, like how currency amounts are specified. + */ source_currencies?: SourceCurrencyAmount + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex } interface PathOption { + /** Array of arrays of objects defining payment paths. */ paths_computed: Path[] + /** + * Currency amount that the source would have to send along this path for the + * destination to receive the desired amount. + */ source_amount: Amount } +/** + * Response expected from a {@link RipplePathFindRequest}. + * + * @category Responses + */ export interface RipplePathFindResponse extends BaseResponse { result: { + /** + * Array of objects with possible paths to take, as described below. If + * empty, then there are no paths connecting the source and destination + * accounts. + */ alternatives: PathOption[] + /** Unique address of the account that would receive a payment transaction. */ destination_account: string + /** + * Array of strings representing the currencies that the destination + * accepts, as 3-letter codes like "USD" or as 40-character hex like + * "015841551A748AD2C1F76FF6ECB0CCCD00000000". + */ destination_currencies: string[] destination_amount: Amount full_reply?: boolean diff --git a/src/models/methods/serverInfo.ts b/src/models/methods/serverInfo.ts index 94a423d1..4a25cf9a 100644 --- a/src/models/methods/serverInfo.ts +++ b/src/models/methods/serverInfo.ts @@ -1,5 +1,12 @@ import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `server_info` command asks the server for a human-readable version of + * various information about the rippled server being queried. Expects a + * response in the form of a {@link ServerInfoResponse}. + * + * @category Requests + */ export interface ServerInfoRequest extends BaseRequest { command: 'server_info' } @@ -26,11 +33,28 @@ export interface JobType { in_progress?: number } +/** + * Response expected from a {@link ServerInfoRequest}. + * + * @category Responses + */ export interface ServerInfoResponse extends BaseResponse { result: { info: { + /** + * If true, this server is amendment blocked. If the server is not + * amendment blocked, the response omits this field. + */ amendment_blocked?: boolean + /** The version number of the running rippled version. */ build_version: string + /** + * Information on the most recently closed ledger that has not been + * validated by consensus. If the most recently validated ledger is + * available, the response omits this field and includes + * `validated_ledger` instead. The member fields are the same as the. + * `validated_ledger` field. + */ closed_ledger?: { age: number base_fee_xrp: number @@ -39,43 +63,169 @@ export interface ServerInfoResponse extends BaseResponse { reserve_inc_xrp: number seq: number } + /** + * Range expression indicating the sequence numbers of the ledger + * versions the local rippled has in its database. + */ complete_ledgers: string + /** + * On an admin request, returns the hostname of the server running the + * rippled instance; otherwise, returns a single RFC-1751 word based on + * the node public key. + */ hostid: string + /** + * Amount of time spent waiting for I/O operations, in milliseconds. If + * this number is not very, very low, then the rippled server is probably + * having serious load issues. + */ io_latency_ms: number + /** + * The number of times (since starting up) that this server has had over + * 250 transactions waiting to be processed at once. A large number here + * may mean that your server is unable to handle the transaction load of + * the XRP Ledger network. + */ jq_trans_overflow: string + /** + * Information about the last time the server closed a ledger, including + * the amount of time it took to reach a consensus and the number of + * trusted validators participating. + */ last_close: { + /** + * The amount of time it took to reach a consensus on the most recently + * validated ledger version, in seconds. + */ converge_time_s: number + /** + * How many trusted validators the server considered (including itself, + * if configured as a validator) in the consensus process for the most + * recently validated ledger version. + */ proposers: number } + /** + * (Admin only) Detailed information about the current load state of the + * server. + */ load?: { + /** + * (Admin only) Information about the rate of different types of jobs + * the server is doing and how much time it spends on each. + */ job_types: JobType[] + /** (Admin only) The number of threads in the server's main job pool. */ threads: number } + /** + * The load-scaled open ledger transaction cost the server is currently + * enforcing, as a multiplier on the base transaction cost. For example, + * at 1000 load factor and a reference transaction cost of 10 drops of + * XRP, the load-scaled transaction cost is 10,000 drops (0.01 XRP). The + * load factor is determined by the highest of the individual server's + * load factor, the cluster's load factor, the open ledger cost and the + * overall network's load factor. + */ load_factor?: number + /** + * Current multiplier to the transaction cost based on + * load to this server. + */ load_factor_local?: number + /** + * Current multiplier to the transaction cost being used by the rest of + * the network. + */ load_factor_net?: number + /** + * Current multiplier to the transaction cost based on load to servers + * in this cluster. + */ load_factor_cluster?: number + /** + * The current multiplier to the transaction cost that a transaction must + * pay to get into the open ledger. + */ load_factor_fee_escalation?: number + /** + * The current multiplier to the transaction cost that a transaction must + * pay to get into the queue, if the queue is full. + */ load_factor_fee_queue?: number + /** + * The load factor the server is enforcing, not including the open ledger + * cost. + */ load_factor_server?: number network_ledger?: 'waiting' + /** How many other rippled servers this one is currently connected to. */ peers: number + /** + * Public key used to verify this server for peer-to-peer communications. + * This node key pair is automatically generated by the server the first + * time it starts up. (If deleted, the server can create a new pair of + * Keys.). + */ pubkey_node: string + /** Public key used by this node to sign ledger validations. */ pubkey_validator?: string + /** + * A string indicating to what extent the server is participating in the + * network. + */ server_state: ServerState + /** + * The number of consecutive microseconds the server has been in the + * current state. + */ server_state_duration_us: number + /** + * A map of various server states with information about the time the + * server spends in each. This can be useful for tracking the long-term + * health of your server's connectivity to the network. + */ state_accounting: Record + /** The current time in UTC, according to the server's clock. */ time: string + /** Number of consecutive seconds that the server has been operational. */ uptime: number + /** Information about the most recent fully-validated ledger. */ validated_ledger?: { + /** The time since the ledger was closed, in seconds. */ age: number + /** + * Base fee, in XRP. This may be represented in scientific notation. + * Such as 1e-05 for 0.00005. + */ base_fee_xrp: number + /** Unique hash for the ledger, as hexadecimal. */ hash: string + /** + * Minimum amount of XRP (not drops) necessary for every account to. + * Keep in reserve . + */ reserve_base_xrp: number + /** + * Amount of XRP (not drops) added to the account reserve for each + * object an account owns in the ledger. + */ reserve_inc_xrp: number + /** The ledger index of the latest validated ledger. */ seq: number } + /** + * Minimum number of trusted validations required to validate a ledger + * version. Some circumstances may cause the server to require more + * validations. + */ validation_quorum: number + /** + * Either the human readable time, in UTC, when the current validator + * list will expire, the string unknown if the server has yet to load a + * published validator list or the string never if the server uses a + * static validator list. + */ validator_list_expires?: string } } diff --git a/src/models/methods/serverState.ts b/src/models/methods/serverState.ts index eac233e7..b79f774b 100644 --- a/src/models/methods/serverState.ts +++ b/src/models/methods/serverState.ts @@ -1,9 +1,23 @@ import { BaseRequest, BaseResponse } from './baseMethod' import { JobType, ServerState, StateAccounting } from './serverInfo' +/** + * The `server_state` command asks the server for various machine-readable + * information about the rippled server's current state. The response is almost + * the same as the server_info method, but uses units that are easier to process + * instead of easier to read. + * + * @category Requests + */ export interface ServerStateRequest extends BaseRequest { command: 'server_state' } + +/** + * Response expected from a {@link ServerStateRequest}. + * + * @category Responses + */ export interface ServerStateResponse extends BaseResponse { result: { state: { diff --git a/src/models/methods/submit.ts b/src/models/methods/submit.ts index e7d07d8a..7de1b844 100644 --- a/src/models/methods/submit.ts +++ b/src/models/methods/submit.ts @@ -2,27 +2,93 @@ import { Transaction } from '../transactions' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The submit method applies a transaction and sends it to the network to be + * confirmed and included in future ledgers. Expects a response in the form of a + * {@link SubmitResponse}. + * + * @category Requests + */ export interface SubmitRequest extends BaseRequest { command: 'submit' + /** The complete transaction in hex string format. */ tx_blob: string + /** + * If true, and the transaction fails locally, do not retry or relay the + * transaction to other servers. The default is false. + */ fail_hard?: boolean } +/** + * Response expected from a {@link SubmitRequest}. + * + * @category Responses + */ export interface SubmitResponse extends BaseResponse { result: { + /** + * Text result code indicating the preliminary result of the transaction, + * for example `tesSUCCESS`. + */ engine_result: string + /** Numeric version of the result code. */ engine_result_code: number + /** Human-readable explanation of the transaction's preliminary result. */ engine_result_message: string + /** The complete transaction in hex string format. */ tx_blob: string + /** The complete transaction in JSON format. */ tx_json: Transaction & { hash?: string } + /** + * The value true indicates that the transaction was applied, queued, + * broadcast, or kept for later. The value `false` indicates that none of + * those happened, so the transaction cannot possibly succeed as long as you + * do not submit it again and have not already submitted it another time. + */ accepted: boolean + /** + * The next Sequence Number available for the sending account after all + * pending and queued transactions. + */ account_sequence_available: number + /** + * The next Sequence number for the sending account after all transactions + * that have been provisionally applied, but not transactions in the queue. + */ account_sequence_next: number + /** + * The value true indicates that this transaction was applied to the open + * ledger. In this case, the transaction is likely, but not guaranteed, to + * be validated in the next ledger version. + */ applied: boolean + /** + * The value true indicates this transaction was broadcast to peer servers + * in the peer-to-peer XRP Ledger network. + */ broadcast: boolean + /** + * The value true indicates that the transaction was kept to be retried + * later. + */ kept: boolean + /** + * The value true indicates the transaction was put in the Transaction + * Queue, which means it is likely to be included in a future ledger + * version. + */ queued: boolean + /** + * The current open ledger cost before processing this transaction + * transactions with a lower cost are likely to be queued. + */ open_ledger_cost: string + /** + * The ledger index of the newest validated ledger at the time of + * submission. This provides a lower bound on the ledger versions that the + * transaction can appear in as a result of this request. + */ validated_ledger_index: number } } diff --git a/src/models/methods/submitMultisigned.ts b/src/models/methods/submitMultisigned.ts index 7c1c9bae..2398418b 100644 --- a/src/models/methods/submitMultisigned.ts +++ b/src/models/methods/submitMultisigned.ts @@ -2,18 +2,50 @@ import { Transaction } from '../transactions' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `submit_multisigned` command applies a multi-signed transaction and sends + * it to the network to be included in future ledgers. Expects a response in the + * form of a {@link SubmitMultisignedRequest}. + * + * @category Requests + */ export interface SubmitMultisignedRequest extends BaseRequest { command: 'submit_multisigned' + /** + * Transaction in JSON format with an array of Signers. To be successful, the + * weights of the signatures must be equal or higher than the quorum of the. + * {@link SignerList}. + */ tx_json: Transaction + /** + * If true, and the transaction fails locally, do not retry or relay the + * transaction to other servers. + */ fail_hard?: boolean } +/** + * Response expected from a {@link SubmitMultisignedRequest}. + * + * @category Responses + */ export interface SubmitMultisignedResponse extends BaseResponse { result: { + /** + * Code indicating the preliminary result of the transaction, for example. + * `tesSUCCESS` . + */ engine_result: string + /** + * Numeric code indicating the preliminary result of the transaction, + * directly correlated to `engine_result`. + */ engine_result_code: number + /** Human-readable explanation of the preliminary transaction result. */ engine_result_message: string + /** The complete transaction in hex string format. */ tx_blob: string + /** The complete transaction in JSON format. */ tx_json: Transaction & { hash?: string } } } diff --git a/src/models/methods/subscribe.ts b/src/models/methods/subscribe.ts index f198874e..0839431b 100644 --- a/src/models/methods/subscribe.ts +++ b/src/models/methods/subscribe.ts @@ -5,93 +5,284 @@ import TransactionMetadata from '../transactions/metadata' import type { BaseRequest, BaseResponse } from './baseMethod' interface Book { + /** + * Specification of which currency the account taking the Offer would + * receive, as a currency object with no amount. + */ taker_gets: Currency + /** + * Specification of which currency the account taking the Offer would pay, as + * a currency object with no amount. + */ taker_pays: Currency + /** + * Unique account address to use as a perspective for viewing offers, in the. + * XRP Ledger's base58 format. + */ taker: string + /** + * If true, return the current state of the order book once when you + * subscribe before sending updates. The default is false. + */ snapshot?: boolean + /** If true, return both sides of the order book. The default is false. */ both?: boolean } +/** + * The subscribe method requests periodic notifications from the server when + * certain events happen. Expects a response in the form of a. + * {@link SubscribeResponse}. + * + * @category Requests + */ export interface SubscribeRequest extends BaseRequest { command: 'subscribe' + /** Array of string names of generic streams to subscribe to. */ streams?: StreamType[] + /** + * Array with the unique addresses of accounts to monitor for validated + * transactions. The addresses must be in the XRP Ledger's base58 format. + * The server sends a notification for any transaction that affects at least + * one of these accounts. + */ accounts?: string[] + /** Like accounts, but include transactions that are not yet finalized. */ accounts_proposed?: string[] + /** + * Array of objects defining order books to monitor for updates, as detailed + * Below. + */ books?: Book[] + /** + * URL where the server sends a JSON-RPC callbacks for each event. + * Admin-only. + */ url?: string + /** Username to provide for basic authentication at the callback URL. */ url_username?: string + /** Password to provide for basic authentication at the callback URL. */ url_password?: string } +/** + * Response expected from a {@link SubscribeRequest}. + * + * @category Responses + */ export interface SubscribeResponse extends BaseResponse { - // TODO: figure out if there's a better way to type this - // eslint-disable-next-line @typescript-eslint/ban-types -- actually should be an empty object - result: {} | Stream + result: Record | Stream } interface BaseStream { type: string } +/** + * The `ledger` stream only sends `ledgerClosed` messages when the consensus + * process declares a new validated ledger. The message identifies the ledger + * And provides some information about its contents. + * + * @category Streams + */ export interface LedgerStream extends BaseStream { type: 'ledgerClosed' + /** + * The reference transaction cost as of this ledger version, in drops of XRP. + * If this ledger version includes a SetFee pseudo-transaction the new. + * Transaction cost applies starting with the following ledger version. + */ fee_base: number + /** The reference transaction cost in "fee units". */ fee_ref: number + /** The identifying hash of the ledger version that was closed. */ ledger_hash: string + /** The ledger index of the ledger that was closed. */ ledger_index: number + /** The time this ledger was closed, in seconds since the Ripple Epoch. */ ledger_time: number + /** + * The minimum reserve, in drops of XRP, that is required for an account. If + * this ledger version includes a SetFee pseudo-transaction the new base reserve + * applies starting with the following ledger version. + */ reserve_base: number + /** + * The owner reserve for each object an account owns in the ledger, in drops + * of XRP. If the ledger includes a SetFee pseudo-transaction the new owner + * reserve applies after this ledger. + */ reserve_inc: number + /** Number of new transactions included in this ledger version. */ txn_count: number + /** + * Range of ledgers that the server has available. This may be a disjoint + * sequence such as 24900901-24900984,24901116-24901158. This field is not + * returned if the server is not connected to the network, or if it is + * connected but has not yet obtained a ledger from the network. + */ validated_ledgers?: string } +/** + * The validations stream sends messages whenever it receives validation + * messages, also called validation votes, regardless of whether or not the + * validation message is from a trusted validator. + * + * @category Streams + */ export interface ValidationStream extends BaseStream { type: 'validationReceived' + /** + * The value validationReceived indicates this is from the validations + * Stream. + */ amendments?: string[] + /** The amendments this server wants to be added to the protocol. */ base_fee?: number + /** + * The unscaled transaction cost (reference_fee value) this server wants to + * set by Fee voting. + */ flags: number + /** + * Bit-mask of flags added to this validation message. The flag 0x80000000 + * indicates that the validation signature is fully-canonical. The flag + * 0x00000001 indicates that this is a full validation; otherwise it's a + * partial validation. Partial validations are not meant to vote for any + * particular ledger. A partial validation indicates that the validator is + * still online but not keeping up with consensus. + */ full: boolean + /** + * If true, this is a full validation. Otherwise, this is a partial + * validation. Partial validations are not meant to vote for any particular + * ledger. A partial validation indicates that the validator is still online + * but not keeping up with consensus. + */ ledger_hash: string + /** The ledger index of the proposed ledger. */ ledger_index: string + /** + * The local load-scaled transaction cost this validator is currently + * enforcing, in fee units. + */ load_fee?: number + /** + * The validator's master public key, if the validator is using a validator + * token, in the XRP Ledger's base58 format. + */ master_key?: string + /** + * The minimum reserve requirement (`account_reserve` value) this validator + * wants to set by fee voting. + */ reserve_base?: number + /** + * The increment in the reserve requirement (owner_reserve value) this + * validator wants to set by fee voting. + */ reserve_inc?: number + /** The signature that the validator used to sign its vote for this ledger. */ signature: string + /** When this validation vote was signed, in seconds since the Ripple Epoch. */ signing_time: number + /** + * The public key from the key-pair that the validator used to sign the + * message, in the XRP Ledger's base58 format. This identifies the validator + * sending the message and can also be used to verify the signature. If the + * validator is using a token, this is an ephemeral public key. + */ validation_public_key: string } +/** + * Many subscriptions result in messages about transactions. + * + * @category Streams + */ export interface TransactionStream extends BaseStream { status: string type: 'transaction' + /** String Transaction result code. */ engine_result: string + /** Numeric transaction response code, if applicable. */ engine_result_code: number + /** Human-readable explanation for the transaction response. */ engine_result_message: string + /** + * The ledger index of the current in-progress ledger version for which this + * transaction is currently proposed. + */ ledger_current_index?: number + /** The identifying hash of the ledger version that includes this transaction. */ ledger_hash?: string + /** The ledger index of the ledger version that includes this transaction. */ ledger_index?: number + /** + * The transaction metadata, which shows the exact outcome of the transaction + * in detail. + */ meta?: TransactionMetadata + /** The definition of the transaction in JSON format. */ transaction: Transaction + /** + * If true, this transaction is included in a validated ledger and its + * outcome is final. Responses from the transaction stream should always be + * validated. + */ validated?: boolean warnings?: Array<{ id: number; message: string }> } +/** + * The admin-only `peer_status` stream reports a large amount of information on + * the activities of other rippled servers to which this server is connected, in + * particular their status in the consensus process. + * + * @category Streams + */ export interface PeerStatusStream extends BaseStream { type: 'peerStatusChange' + /** + * The type of event that prompted this message. See Peer Status Events for + * possible values. + */ action: 'CLOSING_LEDGER' | 'ACCEPTED_LEDGER' | 'SWITCHED_LEDGER' | 'LOST_SYNC' + /** The time this event occurred, in seconds since the Ripple Epoch. */ date: number + /** The identifying Hash of a ledger version to which this message pertains. */ ledger_hash?: string + /** The Ledger Index of a ledger version to which this message pertains. */ ledger_index?: number + /** The largest Ledger Index the peer has currently available. */ ledger_index_max?: number + /** The smallest Ledger Index the peer has currently available. */ ledger_index_min?: number } +/** + * The format of an order book stream message is the same as that of + * transaction stream messages, except that OfferCreate transactions also + * contain the following field. + */ interface ModifiedOfferCreateTransaction extends OfferCreate { + /** + * Numeric amount of the TakerGets currency that the Account sending this + * OfferCreate transaction has after executing this transaction. This does not + * check whether the currency amount is frozen. + */ owner_funds: string } +/** + * When you subscribe to one or more order books with the `books` field, you + * get back any transactions that affect those order books. Has the same format + * as a {@link TransactionStream} but the transaction can have a `owner_funds` + * field. + * + * @category Streams + */ export interface OrderBookStream extends BaseStream { status: string type: 'transaction' @@ -106,25 +297,62 @@ export interface OrderBookStream extends BaseStream { validated: boolean } +/** + * The consensus stream sends consensusPhase messages when the consensus + * process changes phase. The message contains the new phase of consensus the + * server is in. + * + * @category Streams + */ export interface ConsensusStream extends BaseStream { type: 'consensusPhase' + /** + * The new consensus phase the server is in. Possible values are open, + * establish, and accepted. + */ consensus: 'open' | 'establish' | 'accepted' } +/** + * The path_find method searches for a path along which a transaction can + * possibly be made, and periodically sends updates when the path changes over + * time. + * + * @category Streams + */ export interface PathFindStream extends BaseStream { type: 'path_find' + /** Unique address that would send a transaction. */ source_account: string + /** Unique address of the account that would receive a transaction. */ destination_account: string + /** Currency Amount that the destination would receive in a transaction. */ destination_amount: Amount + /** + * If false, this is the result of an incomplete search. A later reply may + * have a better path. If true, then this is the best path found. (It is still + * theoretically possible that a better path could exist, but rippled won't + * find it.) Until you close the pathfinding request, rippled continues to + * send updates each time a new ledger closes. + */ full_reply: boolean + /** The ID provided in the WebSocket request is included again at this level. */ id: number | string + /** Currency Amount that would be spent in the transaction. */ send_max?: Amount + /** + * Array of objects with suggested paths to take. If empty, then no paths + * were found connecting the source and destination accounts. + */ alternatives: { paths_computed: Path[] source_amount: Amount } } +/** + * @category Streams + */ export type Stream = | LedgerStream | ValidationStream diff --git a/src/models/methods/transactionEntry.ts b/src/models/methods/transactionEntry.ts index 2c808656..cba1d8de 100644 --- a/src/models/methods/transactionEntry.ts +++ b/src/models/methods/transactionEntry.ts @@ -4,18 +4,49 @@ import TransactionMetadata from '../transactions/metadata' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The `transaction_entry` method retrieves information on a single transaction + * from a specific ledger version. Expects a response in the form of a + * {@link TransactionEntryResponse}. + * + * @category Requests + */ export interface TransactionEntryRequest extends BaseRequest { command: 'transaction_entry' + /** A 20-byte hex string for the ledger version to use. */ ledger_hash?: string + /** + * The ledger index of the ledger to use, or a shortcut string to choose a + * ledger automatically. + */ ledger_index?: LedgerIndex + /** Unique hash of the transaction you are looking up. */ tx_hash: string } +/** + * Response expected from a {@link TransactionEntryRequest}. + * + * @category Responses + */ export interface TransactionEntryResponse extends BaseResponse { result: { + /** + * The identifying hash of the ledger version the transaction was found in; + * this is the same as the one from the request. + */ ledger_hash: string + /** + * The ledger index of the ledger version the transaction was found in; + * this is the same as the one from the request. + */ ledger_index: number + /** + * The transaction metadata, which shows the exact results of the + * transaction in detail. + */ metadata: TransactionMetadata + /** JSON representation of the Transaction object. */ tx_json: Transaction } } diff --git a/src/models/methods/tx.ts b/src/models/methods/tx.ts index fb7805ca..616e03cb 100644 --- a/src/models/methods/tx.ts +++ b/src/models/methods/tx.ts @@ -3,20 +3,61 @@ import TransactionMetadata from '../transactions/metadata' import { BaseRequest, BaseResponse } from './baseMethod' +/** + * The tx method retrieves information on a single transaction, by its + * identifying hash. Expects a response in the form of a {@link TxResponse}. + * + * @category Requests + */ export interface TxRequest extends BaseRequest { command: 'tx' transaction: string + /** + * If true, return transaction data and metadata as binary serialized to + * hexadecimal strings. If false, return transaction data and metadata as. + * JSON. The default is false. + */ binary?: boolean + /** + * Use this with max_ledger to specify a range of up to 1000 ledger indexes, + * starting with this ledger (inclusive). If the server cannot find the + * transaction, it confirms whether it was able to search all the ledgers in + * this range. + */ min_ledger?: number + /** + * Use this with min_ledger to specify a range of up to 1000 ledger indexes, + * ending with this ledger (inclusive). If the server cannot find the + * transaction, it confirms whether it was able to search all the ledgers in + * the requested range. + */ max_ledger?: number } +/** + * Response expected from a {@link TxRequest}. + * + * @category Responses + */ export interface TxResponse extends BaseResponse { result: { + /** The SHA-512 hash of the transaction. */ hash: string + /** The ledger index of the ledger that includes this transaction. */ ledger_index?: number + /** Transaction metadata, which describes the results of the transaction. */ meta?: TransactionMetadata | string + /** + * If true, this data comes from a validated ledger version; if omitted or. + * Set to false, this data is not final. + */ validated?: boolean } & Transaction + /** + * If true, the server was able to search all of the specified ledger + * versions, and the transaction was in none of them. If false, the server did + * not have all of the specified ledger versions available, so it is not sure. + * If one of them might contain the transaction. + */ searched_all?: boolean } diff --git a/src/models/methods/unsubscribe.ts b/src/models/methods/unsubscribe.ts index 5fc3a339..597d2e98 100644 --- a/src/models/methods/unsubscribe.ts +++ b/src/models/methods/unsubscribe.ts @@ -8,16 +8,42 @@ interface Book { both?: boolean } +/** + * The unsubscribe command tells the server to stop sending messages for a + * particular subscription or set of subscriptions. Expects a response in the + * form of an {@link UnsubscribeResponse}. + * + * @category Requests + */ export interface UnsubscribeRequest extends BaseRequest { command: 'unsubscribe' + /** + * Array of string names of generic streams to unsubscribe from, including. + * Ledger, server, transactions, and transactions_proposed. + */ streams?: StreamType[] + /** + * Array of unique account addresses to stop receiving updates for, in the. + * XRP Ledger's base58 format. + */ accounts?: string[] + /** + * Like accounts, but for accounts_proposed subscriptions that included + * not-yet-validated transactions. + */ accounts_proposed?: string[] + /** + * Array of objects defining order books to unsubscribe from, as explained + * below. + */ books?: Book[] } +/** + * Response expected from a {@link UnsubscribeRequest}. + * + * @category Responses + */ export interface UnsubscribeResponse extends BaseResponse { - // TODO: figure out if there's a better way to type this - // eslint-disable-next-line @typescript-eslint/ban-types -- actually should be an empty object - result: {} + result: Record } diff --git a/src/models/transactions/accountDelete.ts b/src/models/transactions/accountDelete.ts index 46e505a1..9e8c403c 100644 --- a/src/models/transactions/accountDelete.ts +++ b/src/models/transactions/accountDelete.ts @@ -2,9 +2,25 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * An AccountDelete transaction deletes an account and any objects it owns in + * the XRP Ledger, if possible, sending the account's remaining XRP to a + * specified destination account. + * + * @category Transaction Models + */ export interface AccountDelete extends BaseTransaction { TransactionType: 'AccountDelete' + /** + * The address of an account to receive any leftover XRP after deleting the + * sending account. Must be a funded account in the ledger, and must not be. + * the sending account. + */ Destination: string + /** + * Arbitrary destination tag that identifies a hosted recipient or other. + * information for the recipient of the deleted account's leftover XRP. + */ DestinationTag?: number } diff --git a/src/models/transactions/accountSet.ts b/src/models/transactions/accountSet.ts index 56c99af2..8383fc43 100644 --- a/src/models/transactions/accountSet.ts +++ b/src/models/transactions/accountSet.ts @@ -3,27 +3,71 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * Enum for AccountSet Flags. + * + * @category Transaction Flags + */ export enum AccountSetAsfFlags { + /** Require a destination tag to send transactions to this account. */ asfRequireDest = 1, + /** + * Require authorization for users to hold balances issued by this address + * can only be enabled if the address has no trust lines connected to it. + */ asfRequireAuth = 2, + /** XRP should not be sent to this account. */ asfDisallowXRP = 3, + /** + * Disallow use of the master key pair. Can only be enabled if the account + * has configured another way to sign transactions, such as a Regular Key or a + * Signer List. + */ asfDisableMaster = 4, + /** + * Track the ID of this account's most recent transaction. Required for + * AccountTxnID. + */ asfAccountTxnID = 5, + /** + * Permanently give up the ability to freeze individual trust lines or + * disable Global Freeze. This flag can never be disabled after being enabled. + */ asfNoFreeze = 6, + /** Freeze all assets issued by this account. */ asfGlobalFreeze = 7, + /** Enable rippling on this account's trust lines by default. */ asfDefaultRipple = 8, + /** Enable Deposit Authorization on this account. */ asfDepositAuth = 9, } +/** + * Enum for AccountSet Transaction Flags. + * + * @category Transaction Flags + */ export enum AccountSetTfFlags { + /** The same as SetFlag: asfRequireDest. */ tfRequireDestTag = 0x00010000, + /** The same as ClearFlag: asfRequireDest. */ tfOptionalDestTag = 0x00020000, + /** The same as SetFlag: asfRequireAuth. */ tfRequireAuth = 0x00040000, + /** The same as ClearFlag: asfRequireAuth. */ tfOptionalAuth = 0x00080000, + /** The same as SetFlag: asfDisallowXRP. */ tfDisallowXRP = 0x00100000, + /** The same as ClearFlag: asfDisallowXRP. */ tfAllowXRP = 0x00200000, } +/** + * Map of flags to boolean values representing {@link AccountSet} transaction + * flags. + * + * @category Transaction Flags + */ export interface AccountSetFlagsInterface { tfRequireDestTag?: boolean tfOptionalDestTag?: boolean @@ -33,15 +77,39 @@ export interface AccountSetFlagsInterface { tfAllowXRP?: boolean } +/** + * An AccountSet transaction modifies the properties of an account in the XRP + * Ledger. + * + * @category Transaction Models + */ export interface AccountSet extends BaseTransaction { TransactionType: 'AccountSet' Flags?: number | AccountSetFlagsInterface + /** Unique identifier of a flag to disable for this account. */ ClearFlag?: number + /** + * The domain that owns this account, as a string of hex representing the. + * ASCII for the domain in lowercase. + */ Domain?: string + /** Hash of an email address to be used for generating an avatar image. */ EmailHash?: string + /** Public key for sending encrypted messages to this account. */ MessageKey?: string + /** Integer flag to enable for this account. */ SetFlag?: AccountSetAsfFlags + /** + * The fee to charge when users transfer this account's issued currencies, + * represented as billionths of a unit. Cannot be more than 2000000000 or less + * than 1000000000, except for the special case 0 meaning no fee. + */ TransferRate?: number + /** + * Tick size to use for offers involving a currency issued by this address. + * The exchange rates of those offers is rounded to this many significant + * digits. Valid values are 3 to 15 inclusive, or 0 to disable. + */ TickSize?: number } diff --git a/src/models/transactions/checkCancel.ts b/src/models/transactions/checkCancel.ts index bc572092..6d129a7d 100644 --- a/src/models/transactions/checkCancel.ts +++ b/src/models/transactions/checkCancel.ts @@ -2,8 +2,20 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * Cancels an unredeemed Check, removing it from the ledger without sending any + * money. The source or the destination of the check can cancel a Check at any + * time using this transaction type. If the Check has expired, any address can + * cancel it. + * + * @category Transaction Models + */ export interface CheckCancel extends BaseTransaction { TransactionType: 'CheckCancel' + /** + * The ID of the Check ledger object to cancel as a 64-character hexadecimal + * string. + */ CheckID: string } diff --git a/src/models/transactions/checkCash.ts b/src/models/transactions/checkCash.ts index f78165d5..e4658784 100644 --- a/src/models/transactions/checkCash.ts +++ b/src/models/transactions/checkCash.ts @@ -4,10 +4,31 @@ import { Amount } from '../common' import { BaseTransaction, validateBaseTransaction, isAmount } from './common' +/** + * Attempts to redeem a Check object in the ledger to receive up to the amount + * authorized by the corresponding CheckCreate transaction. Only the Destination + * address of a Check can cash it with a CheckCash transaction. + * + * @category Transaction Models + */ export interface CheckCash extends BaseTransaction { TransactionType: 'CheckCash' + /** + * The ID of the Check ledger object to cash as a 64-character hexadecimal + * string. + */ CheckID: string + /** + * Redeem the Check for exactly this amount, if possible. The currency must + * match that of the SendMax of the corresponding CheckCreate transaction. You. + * must provide either this field or DeliverMin. + */ Amount?: Amount + /** + * Redeem the Check for at least this amount and for as much as possible. The + * currency must match that of the SendMax of the corresponding CheckCreate. + * transaction. You must provide either this field or Amount. + */ DeliverMin?: Amount } diff --git a/src/models/transactions/checkCreate.ts b/src/models/transactions/checkCreate.ts index 43b137f2..332ad79a 100644 --- a/src/models/transactions/checkCreate.ts +++ b/src/models/transactions/checkCreate.ts @@ -8,12 +8,39 @@ import { isIssuedCurrency, } from './common' +/** + * Create a Check object in the ledger, which is a deferred payment that can be + * cashed by its intended destination. The sender of this transaction is the + * sender of the Check. + * + * @category Transaction Models + */ export interface CheckCreate extends BaseTransaction { TransactionType: 'CheckCreate' + /** The unique address of the account that can cash the Check. */ Destination: string + /** + * Maximum amount of source currency the Check is allowed to debit the + * sender, including transfer fees on non-XRP currencies. The Check can only + * credit the destination with the same currency (from the same issuer, for + * non-XRP currencies). For non-XRP amounts, the nested field names MUST be. + * lower-case. + */ SendMax: Amount + /** + * Arbitrary tag that identifies the reason for the Check, or a hosted. + * recipient to pay. + */ DestinationTag?: number + /** + * Time after which the Check is no longer valid, in seconds since the Ripple. + * Epoch. + */ Expiration?: number + /** + * Arbitrary 256-bit hash representing a specific reason or identifier for. + * this Check. + */ InvoiceID?: string } diff --git a/src/models/transactions/common.ts b/src/models/transactions/common.ts index 2510cbab..3b9ce74b 100644 --- a/src/models/transactions/common.ts +++ b/src/models/transactions/common.ts @@ -104,20 +104,78 @@ export function isAmount(amount: unknown): boolean { // eslint-disable-next-line @typescript-eslint/no-empty-interface -- no global flags right now, so this is fine export interface GlobalFlags {} +/** + * Every transaction has the same set of common fields. + */ export interface BaseTransaction { + /** The unique address of the account that initiated the transaction. */ Account: string + /** + * The type of transaction. Valid types include: `Payment`, `OfferCreate`, + * `SignerListSet`, `EscrowCreate`, `EscrowFinish`, `EscrowCancel`, + * `PaymentChannelCreate`, `PaymentChannelFund`, `PaymentChannelClaim`, and + * `DepositPreauth`. + */ TransactionType: string + /** + * Integer amount of XRP, in drops, to be destroyed as a cost for + * distributing this transaction to the network. Some transaction types have + * different minimum requirements. + */ Fee?: string + /** + * The sequence number of the account sending the transaction. A transaction + * is only valid if the Sequence number is exactly 1 greater than the previous + * transaction from the same account. The special case 0 means the transaction + * is using a Ticket instead. + */ Sequence?: number + /** + * Hash value identifying another transaction. If provided, this transaction + * is only valid if the sending account's previously-sent transaction matches + * the provided hash. + */ AccountTxnID?: string + /** Set of bit-flags for this transaction. */ Flags?: number | GlobalFlags + /** + * Highest ledger index this transaction can appear in. Specifying this field + * places a strict upper limit on how long the transaction can wait to be + * validated or rejected. + */ LastLedgerSequence?: number // TODO: Make Memo match the format of Signer (By including the Memo: wrapper inside the Interface) + /** + * Additional arbitrary information used to identify this transaction. + */ Memos?: Array<{ Memo: Memo }> + /** + * Array of objects that represent a multi-signature which authorizes this + * transaction. + */ Signers?: Signer[] + /** + * Arbitrary integer used to identify the reason for this payment, or a sender + * on whose behalf this transaction is made. Conventionally, a refund should + * specify the initial payment's SourceTag as the refund payment's + * DestinationTag. + */ SourceTag?: number + /** + * Hex representation of the public key that corresponds to the private key + * used to sign this transaction. If an empty string, indicates a + * multi-signature is present in the Signers field instead. + */ SigningPubKey?: string + /** + * The sequence number of the ticket to use in place of a Sequence number. If + * this is provided, Sequence must be 0. Cannot be used with AccountTxnID. + */ TicketSequence?: number + /** + * The signature that verifies this transaction as originating from the + * account it says it is from. + */ TxnSignature?: string } diff --git a/src/models/transactions/depositPreauth.ts b/src/models/transactions/depositPreauth.ts index 68c9238c..802488e8 100644 --- a/src/models/transactions/depositPreauth.ts +++ b/src/models/transactions/depositPreauth.ts @@ -3,9 +3,21 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * A DepositPreauth transaction gives another account pre-approval to deliver + * payments to the sender of this transaction. This is only useful if the sender + * of this transaction is using (or plans to use) Deposit Authorization. + * + * @category Transaction Models + */ export interface DepositPreauth extends BaseTransaction { TransactionType: 'DepositPreauth' + /** The XRP Ledger address of the sender to preauthorize. */ Authorize?: string + /** + * The XRP Ledger address of a sender whose preauthorization should be. + * revoked. + */ Unauthorize?: string } diff --git a/src/models/transactions/escrowCancel.ts b/src/models/transactions/escrowCancel.ts index f4dbe7a5..573d504f 100644 --- a/src/models/transactions/escrowCancel.ts +++ b/src/models/transactions/escrowCancel.ts @@ -2,9 +2,19 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * Return escrowed XRP to the sender. + * + * @category Transaction Models + */ export interface EscrowCancel extends BaseTransaction { TransactionType: 'EscrowCancel' + /** Address of the source account that funded the escrow payment. */ Owner: string + /** + * Transaction sequence (or Ticket number) of EscrowCreate transaction that. + * created the escrow to cancel. + */ OfferSequence: number } diff --git a/src/models/transactions/escrowCreate.ts b/src/models/transactions/escrowCreate.ts index 094244a5..aeb2d88b 100644 --- a/src/models/transactions/escrowCreate.ts +++ b/src/models/transactions/escrowCreate.ts @@ -3,13 +3,42 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * Sequester XRP until the escrow process either finishes or is canceled. + * + * @category Transaction Models + */ export interface EscrowCreate extends BaseTransaction { TransactionType: 'EscrowCreate' + /** + * Amount of XRP, in drops, to deduct from the sender's balance and escrow. + * Once escrowed, the XRP can either go to the Destination address (after the. + * FinishAfter time) or returned to the sender (after the CancelAfter time). + */ Amount: string + /** Address to receive escrowed XRP. */ Destination: string + /** + * The time, in seconds since the Ripple Epoch, when this escrow expires. + * This value is immutable; the funds can only be returned the sender after. + * this time. + */ CancelAfter?: number + /** + * The time, in seconds since the Ripple Epoch, when the escrowed XRP can be + * released to the recipient. This value is immutable; the funds cannot move. + * until this time is reached. + */ FinishAfter?: number + /** + * Hex value representing a PREIMAGE-SHA-256 crypto-condition . The funds can. + * only be delivered to the recipient if this condition is fulfilled. + */ Condition?: string + /** + * Arbitrary tag to further specify the destination for this escrowed. + * payment, such as a hosted recipient at the destination address. + */ DestinationTag?: number } diff --git a/src/models/transactions/escrowFinish.ts b/src/models/transactions/escrowFinish.ts index 9d70b42b..7a362018 100644 --- a/src/models/transactions/escrowFinish.ts +++ b/src/models/transactions/escrowFinish.ts @@ -2,11 +2,29 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * Deliver XRP from a held payment to the recipient. + * + * @category Transaction Models + */ export interface EscrowFinish extends BaseTransaction { TransactionType: 'EscrowFinish' + /** Address of the source account that funded the held payment. */ Owner: string + /** + * Transaction sequence of EscrowCreate transaction that created the held. + * payment to finish. + */ OfferSequence: number + /** + * Hex value matching the previously-supplied PREIMAGE-SHA-256. + * crypto-condition of the held payment. + */ Condition?: string + /** + * Hex value of the PREIMAGE-SHA-256 crypto-condition fulfillment matching. + * the held payment's Condition. + */ Fulfillment?: string } diff --git a/src/models/transactions/index.ts b/src/models/transactions/index.ts index 2fd4815d..5da2bde4 100644 --- a/src/models/transactions/index.ts +++ b/src/models/transactions/index.ts @@ -1,35 +1,33 @@ -// TODO: replace * imports with direct imports -export * from './transaction' +export { validate, TransactionAndMetadata, Transaction } from './transaction' export { + AccountSetAsfFlags, + AccountSetTfFlags, AccountSetFlagsInterface, AccountSet, - validateAccountSet, } from './accountSet' -export * from './accountDelete' -export * from './checkCancel' -export * from './checkCash' -export * from './checkCreate' -export * from './depositPreauth' -export * from './escrowCancel' -export * from './escrowCreate' -export * from './escrowFinish' -export * from './offerCancel' +export { AccountDelete } from './accountDelete' +export { CheckCancel } from './checkCancel' +export { CheckCash } from './checkCash' +export { CheckCreate } from './checkCreate' +export { DepositPreauth } from './depositPreauth' +export { EscrowCancel } from './escrowCancel' +export { EscrowCreate } from './escrowCreate' +export { EscrowFinish } from './escrowFinish' +export { OfferCancel } from './offerCancel' export { + OfferCreateFlags, OfferCreateFlagsInterface, OfferCreate, - validateOfferCreate, } from './offerCreate' -export { PaymentFlagsInterface, Payment, validatePayment } from './payment' +export { PaymentFlags, PaymentFlagsInterface, Payment } from './payment' export { + PaymentChannelClaimFlags, PaymentChannelClaimFlagsInterface, PaymentChannelClaim, - validatePaymentChannelClaim, } from './paymentChannelClaim' -export * from './paymentChannelCreate' -export * from './paymentChannelFund' -export * from './setRegularKey' -export * from './signerListSet' -export * from './ticketCreate' -export { TrustSetFlagsInterface, TrustSet, validateTrustSet } from './trustSet' - -export { default as setTransactionFlagsToNumber } from '../utils/flags' +export { PaymentChannelCreate } from './paymentChannelCreate' +export { PaymentChannelFund } from './paymentChannelFund' +export { SetRegularKey } from './setRegularKey' +export { SignerListSet } from './signerListSet' +export { TicketCreate } from './ticketCreate' +export { TrustSetFlagsInterface, TrustSetFlags, TrustSet } from './trustSet' diff --git a/src/models/transactions/offerCancel.ts b/src/models/transactions/offerCancel.ts index 4d886fee..4989d188 100644 --- a/src/models/transactions/offerCancel.ts +++ b/src/models/transactions/offerCancel.ts @@ -2,8 +2,19 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * An OfferCancel transaction removes an Offer object from the XRP Ledger. + * + * @category Transaction Models + */ export interface OfferCancel extends BaseTransaction { TransactionType: 'OfferCancel' + /** + * The sequence number (or Ticket number) of a previous OfferCreate + * transaction. If specified, cancel any offer object in the ledger that was + * created by that transaction. It is not considered an error if the offer. + * specified does not exist. + */ OfferSequence: number } diff --git a/src/models/transactions/offerCreate.ts b/src/models/transactions/offerCreate.ts index 9129111c..709c0acc 100644 --- a/src/models/transactions/offerCreate.ts +++ b/src/models/transactions/offerCreate.ts @@ -9,13 +9,48 @@ import { isAmount, } from './common' +/** + * Transaction Flags for an OfferCreate Transaction. + * + * @category Transaction Flags + */ export enum OfferCreateFlags { + /** + * If enabled, the offer does not consume offers that exactly match it, and + * instead becomes an Offer object in the ledger. It still consumes offers + * that cross it. + */ tfPassive = 0x00010000, + /** + * Treat the offer as an Immediate or Cancel order. If enabled, the offer + * never becomes a ledger object: it only tries to match existing offers in + * the ledger. If the offer cannot match any offers immediately, it executes + * "successfully" without trading any currency. In this case, the transaction + * has the result code tesSUCCESS, but creates no Offer objects in the ledger. + */ tfImmediateOrCancel = 0x00020000, + /** + * Treat the offer as a Fill or Kill order . Only try to match existing + * offers in the ledger, and only do so if the entire TakerPays quantity can + * be obtained. If the fix1578 amendment is enabled and the offer cannot be + * executed when placed, the transaction has the result code tecKILLED; + * otherwise, the transaction uses the result code tesSUCCESS even when it was + * killed without trading any currency. + */ tfFillOrKill = 0x00040000, + /** + * Exchange the entire TakerGets amount, even if it means obtaining more than + * the TakerPays amount in exchange. + */ tfSell = 0x00080000, } +/** + * Map of flags to boolean values representing {@link OfferCreate} transaction + * flags. + * + * @category Transaction Flags + */ export interface OfferCreateFlagsInterface extends GlobalFlags { tfPassive?: boolean tfImmediateOrCancel?: boolean @@ -23,12 +58,26 @@ export interface OfferCreateFlagsInterface extends GlobalFlags { tfSell?: boolean } +/** + * An OfferCreate transaction is effectively a limit order . It defines an + * intent to exchange currencies, and creates an Offer object if not completely. + * Fulfilled when placed. Offers can be partially fulfilled. + * + * @category Transaction Models + */ export interface OfferCreate extends BaseTransaction { TransactionType: 'OfferCreate' Flags?: number | OfferCreateFlagsInterface + /** + * Time after which the offer is no longer active, in seconds since the. + * Ripple Epoch. + */ Expiration?: number + /** An offer to delete first, specified in the same way as OfferCancel. */ OfferSequence?: number + /** The amount and type of currency being provided by the offer creator. */ TakerGets: Amount + /** The amount and type of currency being requested by the offer creator. */ TakerPays: Amount } diff --git a/src/models/transactions/payment.ts b/src/models/transactions/payment.ts index a3dbb96f..8c188a03 100644 --- a/src/models/transactions/payment.ts +++ b/src/models/transactions/payment.ts @@ -10,25 +10,104 @@ import { validateBaseTransaction, } from './common' +/** + * Enum representing values for Payment Transaction Flags. + * + * @category Transaction Flags + */ export enum PaymentFlags { + /** + * Do not use the default path; only use paths included in the Paths field. + * This is intended to force the transaction to take arbitrage opportunities. + * Most clients do not need this. + */ tfNoDirectRipple = 0x00010000, + /** + * If the specified Amount cannot be sent without spending more than SendMax, + * reduce the received amount instead of failing outright. See Partial. + * Payments for more details. + */ tfPartialPayment = 0x00020000, + /** + * Only take paths where all the conversions have an input:output ratio that + * is equal or better than the ratio of Amount:SendMax. See Limit Quality for + * details. + */ tfLimitQuality = 0x00040000, } +/** + * Map of flags to boolean values representing {@link Payment} transaction + * flags. + * + * @category Transaction Flags + */ export interface PaymentFlagsInterface extends GlobalFlags { + /** + * Do not use the default path; only use paths included in the Paths field. + * This is intended to force the transaction to take arbitrage opportunities. + * Most clients do not need this. + */ tfNoDirectRipple?: boolean + /** + * If the specified Amount cannot be sent without spending more than SendMax, + * reduce the received amount instead of failing outright. See Partial. + * Payments for more details. + */ tfPartialPayment?: boolean + /** + * Only take paths where all the conversions have an input:output ratio that + * is equal or better than the ratio of Amount:SendMax. See Limit Quality for + * details. + */ tfLimitQuality?: boolean } + +/** + * A Payment transaction represents a transfer of value from one account to + * another. + * + * @category Transaction Models + */ export interface Payment extends BaseTransaction { TransactionType: 'Payment' + /** + * The amount of currency to deliver. For non-XRP amounts, the nested field + * names MUST be lower-case. If the tfPartialPayment flag is set, deliver up + * to this amount instead. + */ Amount: Amount + /** The unique address of the account receiving the payment. */ Destination: string + /** + * Arbitrary tag that identifies the reason for the payment to the + * destination, or a hosted recipient to pay. + */ DestinationTag?: number + /** + * Arbitrary 256-bit hash representing a specific reason or identifier for + * this payment. + */ InvoiceID?: string + /** + * Array of payment paths to be used for this transaction. Must be omitted + * for XRP-to-XRP transactions. + */ Paths?: Path[] + /** + * Highest amount of source currency this transaction is allowed to cost, + * including transfer fees, exchange rates, and slippage . Does not include + * the XRP destroyed as a cost for submitting the transaction. For non-XRP + * amounts, the nested field names MUST be lower-case. Must be supplied for + * cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP + * Payments. + */ SendMax?: Amount + /** + * Minimum amount of destination currency this transaction should deliver. + * Only valid if this is a partial payment. For non-XRP amounts, the nested + * field names are lower-case. + */ DeliverMin?: Amount Flags?: number | PaymentFlagsInterface } diff --git a/src/models/transactions/paymentChannelClaim.ts b/src/models/transactions/paymentChannelClaim.ts index 641ae1da..9d83767e 100644 --- a/src/models/transactions/paymentChannelClaim.ts +++ b/src/models/transactions/paymentChannelClaim.ts @@ -3,23 +3,97 @@ import { ValidationError } from '../../errors' import { BaseTransaction, GlobalFlags, validateBaseTransaction } from './common' +/** + * Enum representing values for PaymentChannelClaim transaction flags. + * + * @category Transaction Flags + */ export enum PaymentChannelClaimFlags { + /** + * Clear the channel's Expiration time. (Expiration is different from the + * channel's immutable CancelAfter time.) Only the source address of the + * payment channel can use this flag. + */ tfRenew = 0x00010000, + /** + * Request to close the channel. Only the channel source and destination + * addresses can use this flag. This flag closes the channel immediately if it + * has no more XRP allocated to it after processing the current claim, or if + * the destination address uses it. If the source address uses this flag when + * the channel still holds XRP, this schedules the channel to close after + * SettleDelay seconds have passed. (Specifically, this sets the Expiration of + * the channel to the close time of the previous ledger plus the channel's + * SettleDelay time, unless the channel already has an earlier Expiration + * time.) If the destination address uses this flag when the channel still + * holds XRP, any XRP that remains after processing the claim is returned to + * the source address. + */ tfClose = 0x00020000, } +/** + * Map of flags to boolean values representing {@link PaymentChannelClaim} + * transaction flags. + * + * @category Transaction Flags + */ export interface PaymentChannelClaimFlagsInterface extends GlobalFlags { + /** + * Clear the channel's Expiration time. (Expiration is different from the + * channel's immutable CancelAfter time.) Only the source address of the + * payment channel can use this flag. + */ tfRenew?: boolean + /** + * Request to close the channel. Only the channel source and destination + * addresses can use this flag. This flag closes the channel immediately if it + * has no more XRP allocated to it after processing the current claim, or if + * the destination address uses it. If the source address uses this flag when + * the channel still holds XRP, this schedules the channel to close after + * SettleDelay seconds have passed. (Specifically, this sets the Expiration of + * the channel to the close time of the previous ledger plus the channel's + * SettleDelay time, unless the channel already has an earlier Expiration + * time.) If the destination address uses this flag when the channel still + * holds XRP, any XRP that remains after processing the claim is returned to + * the source address. + */ tfClose?: boolean } +/** + * Claim XRP from a payment channel, adjust the payment channel's expiration, + * or both. + */ export interface PaymentChannelClaim extends BaseTransaction { TransactionType: 'PaymentChannelClaim' Flags?: number | PaymentChannelClaimFlagsInterface + /** The unique ID of the channel as a 64-character hexadecimal string. */ Channel: string + /** + * Total amount of XRP, in drops, delivered by this channel after processing + * this claim. Required to deliver XRP. Must be more than the total amount + * delivered by the channel so far, but not greater than the Amount of the + * signed claim. Must be provided except when closing the channel. + */ Balance?: string + /** + * The amount of XRP, in drops, authorized by the Signature. This must match + * the amount in the signed message. This is the cumulative amount of XRP that + * can be dispensed by the channel, including XRP previously redeemed. + */ Amount?: string + /** + * The signature of this claim, as hexadecimal. The signed message contains + * the channel ID and the amount of the claim. Required unless the sender of + * the transaction is the source address of the channel. + */ Signature?: string + /** + * The public key used for the signature, as hexadecimal. This must match the + * PublicKey stored in the ledger for the channel. Required unless the sender + * of the transaction is the source address of the channel and the Signature + * field is omitted. + */ PublicKey?: string } diff --git a/src/models/transactions/paymentChannelCreate.ts b/src/models/transactions/paymentChannelCreate.ts index 400f9c27..6bde2c20 100644 --- a/src/models/transactions/paymentChannelCreate.ts +++ b/src/models/transactions/paymentChannelCreate.ts @@ -3,13 +3,49 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * Create a unidirectional channel and fund it with XRP. The address sending + * this transaction becomes the "source address" of the payment channel. + * + * @category Transaction Models + */ export interface PaymentChannelCreate extends BaseTransaction { TransactionType: 'PaymentChannelCreate' + /** + * Amount of XRP, in drops, to deduct from the sender's balance and set aside + * in this channel. While the channel is open, the XRP can only go to the + * Destination address. When the channel closes, any unclaimed XRP is returned + * to the source address's balance. + */ Amount: string + /** + * Address to receive XRP claims against this channel. This is also known as + * the "destination address" for the channel. + */ Destination: string + /** + * Amount of time the source address must wait before closing the channel if + * it has unclaimed XRP. + */ SettleDelay: number + /** + * The public key of the key pair the source will use to sign claims against + * this channel in hexadecimal. This can be any secp256k1 or ed25519 public + * key. + */ PublicKey: string + /** + * The time, in seconds since the Ripple Epoch, when this channel expires. + * Any transaction that would modify the channel after this time closes the + * channel without otherwise affecting it. This value is immutable; the + * channel can be closed earlier than this time but cannot remain open after + * this time. + */ CancelAfter?: number + /** + * Arbitrary tag to further specify the destination for this payment channel, + * such as a hosted recipient at the destination address. + */ DestinationTag?: number } diff --git a/src/models/transactions/paymentChannelFund.ts b/src/models/transactions/paymentChannelFund.ts index 51667ee5..8c46687a 100644 --- a/src/models/transactions/paymentChannelFund.ts +++ b/src/models/transactions/paymentChannelFund.ts @@ -2,10 +2,35 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * Add additional XRP to an open payment channel, and optionally update the + * expiration time of the channel. Only the source address of the channel can + * use this transaction. + * + * @category Transaction Models + */ export interface PaymentChannelFund extends BaseTransaction { TransactionType: 'PaymentChannelFund' + /** + * The unique ID of the channel to fund as a 64-character hexadecimal + * string. + */ Channel: string + /** + * Amount of XRP in drops to add to the channel. Must be a positive amount + * of XRP. + */ Amount: string + /** + * New Expiration time to set for the channel in seconds since the Ripple + * Epoch. This must be later than either the current time plus the SettleDelay + * of the channel, or the existing Expiration of the channel. After the + * Expiration time, any transaction that would access the channel closes the + * channel without taking its normal action. Any unspent XRP is returned to + * the source address when the channel closes. (Expiration is separate from + * the channel's immutable CancelAfter time.) For more information, see the + * PayChannel ledger object type. + */ Expiration?: number } diff --git a/src/models/transactions/setRegularKey.ts b/src/models/transactions/setRegularKey.ts index 50a9c407..deeee770 100644 --- a/src/models/transactions/setRegularKey.ts +++ b/src/models/transactions/setRegularKey.ts @@ -2,8 +2,19 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * A SetRegularKey transaction assigns, changes, or removes the regular key + * pair associated with an account. + * + * @category Transaction Models + */ export interface SetRegularKey extends BaseTransaction { TransactionType: 'SetRegularKey' + /** + * A base-58-encoded Address that indicates the regular key pair to be + * assigned to the account. If omitted, removes any existing regular key pair. + * from the account. Must not match the master key pair for the address. + */ RegularKey?: string } diff --git a/src/models/transactions/signerListSet.ts b/src/models/transactions/signerListSet.ts index 27030a78..c7dd3c3b 100644 --- a/src/models/transactions/signerListSet.ts +++ b/src/models/transactions/signerListSet.ts @@ -3,9 +3,26 @@ import { SignerEntry } from '../common' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * The SignerListSet transaction creates, replaces, or removes a list of + * signers that can be used to multi-sign a transaction. + * + * @category Transaction Models + */ export interface SignerListSet extends BaseTransaction { TransactionType: 'SignerListSet' + /** + * A target number for the signer weights. A multi-signature from this list + * is valid only if the sum weights of the signatures provided is greater than + * or equal to this value. To delete a signer list, use the value 0. + */ SignerQuorum: number + /** + * Array of SignerEntry objects, indicating the addresses and weights of + * signers in this list. This signer list must have at least 1 member and no + * more than 8 members. No address may appear more than once in the list, nor + * may the Account submitting the transaction appear in the list. + */ SignerEntries: SignerEntry[] } diff --git a/src/models/transactions/ticketCreate.ts b/src/models/transactions/ticketCreate.ts index 4c0e4694..3206ffe5 100644 --- a/src/models/transactions/ticketCreate.ts +++ b/src/models/transactions/ticketCreate.ts @@ -2,8 +2,19 @@ import { ValidationError } from '../../errors' import { BaseTransaction, validateBaseTransaction } from './common' +/** + * A TicketCreate transaction sets aside one or more sequence numbers as + * Tickets. + * + * @category Transaction Models + */ export interface TicketCreate extends BaseTransaction { TransactionType: 'TicketCreate' + /** + * How many Tickets to create. This must be a positive number and cannot + * cause the account to own more than 250 Tickets after executing this + * transaction. + */ TicketCount: number } diff --git a/src/models/transactions/transaction.ts b/src/models/transactions/transaction.ts index c55225db..639a97d5 100644 --- a/src/models/transactions/transaction.ts +++ b/src/models/transactions/transaction.ts @@ -8,12 +8,7 @@ import { ValidationError } from '../../errors' import setTransactionFlagsToNumber from '../utils/flags' import { AccountDelete, validateAccountDelete } from './accountDelete' -import { - AccountSet, - validateAccountSet, - AccountSetAsfFlags, - AccountSetTfFlags, -} from './accountSet' +import { AccountSet, validateAccountSet } from './accountSet' import { CheckCancel, validateCheckCancel } from './checkCancel' import { CheckCash, validateCheckCash } from './checkCash' import { CheckCreate, validateCheckCreate } from './checkCreate' @@ -23,16 +18,11 @@ import { EscrowCreate, validateEscrowCreate } from './escrowCreate' import { EscrowFinish, validateEscrowFinish } from './escrowFinish' import TransactionMetadata from './metadata' import { OfferCancel, validateOfferCancel } from './offerCancel' -import { - OfferCreate, - validateOfferCreate, - OfferCreateFlags, -} from './offerCreate' -import { Payment, validatePayment, PaymentFlags } from './payment' +import { OfferCreate, validateOfferCreate } from './offerCreate' +import { Payment, validatePayment } from './payment' import { PaymentChannelClaim, validatePaymentChannelClaim, - PaymentChannelClaimFlags, } from './paymentChannelClaim' import { PaymentChannelCreate, @@ -45,7 +35,7 @@ import { import { SetRegularKey, validateSetRegularKey } from './setRegularKey' import { SignerListSet, validateSignerListSet } from './signerListSet' import { TicketCreate, validateTicketCreate } from './ticketCreate' -import { TrustSet, validateTrustSet, TrustSetFlags } from './trustSet' +import { TrustSet, validateTrustSet } from './trustSet' export type Transaction = | AccountDelete @@ -182,12 +172,3 @@ export function validate(transaction: Record): void { throw new ValidationError(`Invalid Transaction: ${tx.TransactionType}`) } } - -export { - AccountSetAsfFlags, - AccountSetTfFlags, - OfferCreateFlags, - PaymentFlags, - PaymentChannelClaimFlags, - TrustSetFlags, -} diff --git a/src/models/transactions/trustSet.ts b/src/models/transactions/trustSet.ts index 064bd9c0..bc2a6b0f 100644 --- a/src/models/transactions/trustSet.ts +++ b/src/models/transactions/trustSet.ts @@ -8,26 +8,78 @@ import { validateBaseTransaction, } from './common' +/** + * Enum representing values of {@link TrustSet} transaction flags. + * + * @category Transaction Flags + */ export enum TrustSetFlags { + /** + * Authorize the other party to hold currency issued by this account. (No + * effect unless using the asfRequireAuth AccountSet flag.) Cannot be unset. + */ tfSetfAuth = 0x00010000, + /** + * Enable the No Ripple flag, which blocks rippling between two trust lines. + * of the same currency if this flag is enabled on both. + */ tfSetNoRipple = 0x00020000, + /** Disable the No Ripple flag, allowing rippling on this trust line. */ tfClearNoRipple = 0x00040000, + /** Freeze the trust line. */ tfSetFreeze = 0x00100000, + /** Unfreeze the trust line. */ tfClearFreeze = 0x00200000, } +/** + * Map of flags to boolean values representing {@link TrustSet} transaction + * flags. + * + * @category Transaction Flags + */ export interface TrustSetFlagsInterface extends GlobalFlags { + /** + * Authorize the other party to hold currency issued by this account. (No + * effect unless using the asfRequireAuth AccountSet flag.) Cannot be unset. + */ tfSetfAuth?: boolean + /** + * Enable the No Ripple flag, which blocks rippling between two trust lines + * of the same currency if this flag is enabled on both. + */ tfSetNoRipple?: boolean + /** Disable the No Ripple flag, allowing rippling on this trust line. */ tfClearNoRipple?: boolean + /** Freeze the trust line. */ tfSetFreeze?: boolean + /** Unfreeze the trust line. */ tfClearFreeze?: boolean } +/** + * Create or modify a trust line linking two accounts. + * + * @category Transaction Models + */ export interface TrustSet extends BaseTransaction { TransactionType: 'TrustSet' + /** + * Object defining the trust line to create or modify, in the format of a + * Currency Amount. + */ LimitAmount: Amount + /** + * Value incoming balances on this trust line at the ratio of this number per + * 1,000,000,000 units. A value of 0 is shorthand for treating balances at + * face value. + */ QualityIn?: number + /** + * Value outgoing balances on this trust line at the ratio of this number per + * 1,000,000,000 units. A value of 0 is shorthand for treating balances at + * face value. + */ QualityOut?: number Flags?: number | TrustSetFlagsInterface } diff --git a/src/sugar/autofill.ts b/src/sugar/autofill.ts index 51fc7129..54573f39 100644 --- a/src/sugar/autofill.ts +++ b/src/sugar/autofill.ts @@ -171,8 +171,10 @@ async function calculateFeePerTransactionType( baseFee = await fetchAccountDeleteFee(client) } - // Multi-signed Transaction - // 10 drops × (1 + Number of Signatures Provided) + /* + * Multi-signed Transaction + * 10 drops × (1 + Number of Signatures Provided) + */ if (signersCount > 0) { baseFee = BigNumber.sum(baseFee, scaleValue(netFeeDrops, 1 + signersCount)) } diff --git a/src/sugar/orderbook.ts b/src/sugar/orderbook.ts index 716ae9d8..597ed46a 100644 --- a/src/sugar/orderbook.ts +++ b/src/sugar/orderbook.ts @@ -86,9 +86,11 @@ async function getOrderbook( sell.push(order) } }) - // Sort the orders - // for both buys and sells, lowest quality is closest to mid-market - // we sort the orders so that earlier orders are closer to mid-market + /* + * Sort the orders + * for both buys and sells, lowest quality is closest to mid-market + * we sort the orders so that earlier orders are closer to mid-market + */ return { buy: sortOffers(buy).slice(0, options.limit), sell: sortOffers(sell).slice(0, options.limit), diff --git a/src/sugar/submit.ts b/src/sugar/submit.ts index ea8e6092..4dce7a0d 100644 --- a/src/sugar/submit.ts +++ b/src/sugar/submit.ts @@ -6,7 +6,7 @@ import { TxResponse } from '../models/methods' import { Transaction } from '../models/transactions' import { hashes } from '../utils' -// general time for a ledger to close, in milliseconds +/** Approximate time for a ledger to close, in milliseconds */ const LEDGER_CLOSE_TIME = 4000 async function sleep(ms: number): Promise { @@ -128,10 +128,12 @@ async function submitSignedReliable( // Helper functions -// The core logic of reliable submission. Polls the ledger until the result of the -// transaction can be considered final, meaning it has either been included in a -// validated ledger, or the transaction's lastLedgerSequence has been surpassed by the -// latest ledger sequence (meaning it will never be included in a validated ledger). +/* + * The core logic of reliable submission. This polls the ledger until the result of the + * transaction can be considered final, meaning it has either been included in a + * validated ledger, or the transaction's lastLedgerSequence has been surpassed by the + * latest ledger sequence (meaning it will never be included in a validated ledger). + */ async function waitForFinalTransactionOutcome( client: Client, txHash: string, diff --git a/src/sugar/utils.ts b/src/sugar/utils.ts index f660c512..2ad72598 100644 --- a/src/sugar/utils.ts +++ b/src/sugar/utils.ts @@ -12,9 +12,11 @@ export function ensureClassicAddress(account: string): string { if (isValidXAddress(account)) { const { classicAddress, tag } = xAddressToClassicAddress(account) - // Except for special cases, X-addresses used for requests - // must not have an embedded tag. In other words, - // `tag` should be `false`. + /* + * Except for special cases, X-addresses used for requests + * must not have an embedded tag. In other words, + * `tag` should be `false`. + */ if (tag !== false) { throw new Error( 'This command does not support the use of a tag. Use an address without a tag.', diff --git a/src/utils/balanceChanges.ts b/src/utils/balanceChanges.ts index c754d162..6d59d0e3 100644 --- a/src/utils/balanceChanges.ts +++ b/src/utils/balanceChanges.ts @@ -133,9 +133,11 @@ function getTrustlineQuantity(node: NormalizedNode): BalanceChange[] | null { return null } - // A trustline can be created with a non-zero starting balance - // If an offer is placed to acquire an asset with no existing trustline, - // the trustline can be created when the offer is taken. + /* + * A trustline can be created with a non-zero starting balance. + * If an offer is placed to acquire an asset with no existing trustline, + * the trustline can be created when the offer is taken. + */ const fields = node.NewFields == null ? node.FinalFields : node.NewFields // the balance is always from low node's perspective diff --git a/src/utils/generateAddress.ts b/src/utils/generateAddress.ts index 33fb2fa7..74ecda8f 100644 --- a/src/utils/generateAddress.ts +++ b/src/utils/generateAddress.ts @@ -10,16 +10,18 @@ export interface GeneratedAddress { secret: string } -export interface GenerateAddressOptions { +interface GenerateAddressOptions { // The entropy to use to generate the seed. entropy?: Uint8Array | number[] // The digital signature algorithm to generate an address for. Can be `ecdsa-secp256k1` (default) or `ed25519`. algorithm?: ECDSA - // Specifies whether the address is intended for use on a test network such as Testnet or Devnet. - // If `true`, the address should only be used for testing, and will start with `T`. - // If `false` (default), the address should only be used on mainnet, and will start with `X`. + /* + * Specifies whether the address is intended for use on a test network such as Testnet or Devnet. + * If `true`, the address should only be used for testing, and will start with `T`. + * If `false` (default), the address should only be used on mainnet, and will start with `X`. + */ test?: boolean // If `true`, return the classic address, in addition to the X-address. diff --git a/src/utils/index.ts b/src/utils/index.ts index 4b44dc17..896b108f 100644 --- a/src/utils/index.ts +++ b/src/utils/index.ts @@ -47,6 +47,7 @@ import { xrpToDrops, dropsToXrp } from './xrpConversion' * * @param secret - Secret to test for validity. * @returns True if secret can be derived into a keypair. + * @category Utilities */ function isValidSecret(secret: string): boolean { try { diff --git a/src/utils/xrpConversion.ts b/src/utils/xrpConversion.ts index 090a7517..704551c5 100644 --- a/src/utils/xrpConversion.ts +++ b/src/utils/xrpConversion.ts @@ -30,9 +30,11 @@ export function dropsToXrp(dropsToConvert: BigNumber.Value): string { } } - // Converting to BigNumber and then back to string should remove any - // decimal point followed by zeros, e.g. '1.00'. - // Important: specify base 10 to avoid exponential notation, e.g. '1e-7'. + /* + * Converting to BigNumber and then back to string should remove any + * decimal point followed by zeros, e.g. '1.00'. + * Important: specify base 10 to avoid exponential notation, e.g. '1e-7'. + */ drops = new BigNumber(drops).toString(BASE_TEN) // drops are only whole units @@ -42,9 +44,11 @@ export function dropsToXrp(dropsToConvert: BigNumber.Value): string { ) } - // This should never happen; the value has already been - // validated above. This just ensures BigNumber did not do - // something unexpected. + /* + * This should never happen; the value has already been + * validated above. This just ensures BigNumber did not do + * something unexpected. + */ if (!SANITY_CHECK.exec(drops)) { throw new ValidationError( `dropsToXrp: failed sanity check -` + @@ -79,9 +83,11 @@ export function xrpToDrops(xrpToConvert: BigNumber.Value): string { // Important: specify base 10 to avoid exponential notation, e.g. '1e-7'. xrp = new BigNumber(xrp).toString(BASE_TEN) - // This should never happen; the value has already been - // validated above. This just ensures BigNumber did not do - // something unexpected. + /* + * This should never happen; the value has already been + * validated above. This just ensures BigNumber did not do + * something unexpected. + */ if (!SANITY_CHECK.exec(xrp)) { throw new ValidationError( `xrpToDrops: failed sanity check -` + diff --git a/src/wallet/fundWallet.ts b/src/wallet/fundWallet.ts index 81063c82..6f4a317e 100644 --- a/src/wallet/fundWallet.ts +++ b/src/wallet/fundWallet.ts @@ -33,6 +33,13 @@ const MAX_ATTEMPTS = 20 /** * Generates a random wallet with some amount of XRP (usually 1000 XRP). * + * @example + * ```typescript + * const api = new xrpl.Client("wss://s.altnet.rippletest.net:51233") + * await api.connect() + * const wallet = await api.fundWallet() + * ``` + * * @param this - Client. * @param wallet - An existing XRPL Wallet to fund, if undefined, a new Wallet will be created. * @returns A Wallet on the Testnet or Devnet that contains some amount of XRP. @@ -270,7 +277,7 @@ async function getUpdatedBalance( * @throws When the client url is not on altnet or devnet. */ function getFaucetUrl(client: Client): FaucetNetwork | undefined { - const connectionUrl = client.connection.getUrl() + const connectionUrl = client.url // 'altnet' for Ripple Testnet server and 'testnet' for XRPL Labs Testnet server if (connectionUrl.includes('altnet') || connectionUrl.includes('testnet')) { @@ -290,4 +297,5 @@ const _private = { FaucetNetwork, getFaucetUrl, } + export { _private } diff --git a/src/wallet/index.ts b/src/wallet/index.ts index 20d3f2e0..9216603f 100644 --- a/src/wallet/index.ts +++ b/src/wallet/index.ts @@ -31,15 +31,60 @@ const DEFAULT_DERIVATION_PATH = "m/44'/144'/0'/0/0" function hexFromBuffer(buffer: Buffer): string { return buffer.toString('hex').toUpperCase() } -export interface SignedTxBlobHash { +interface SignedTxBlobHash { tx_blob: string hash: string } /** * A utility for deriving a wallet composed of a keypair (publicKey/privateKey). - * A wallet can be derived from either a seed, mnemnoic, or entropy (array of random numbers). + * A wallet can be derived from either a seed, mnemonic, or entropy (array of random numbers). * It provides functionality to sign/verify transactions offline. + * + * @example + * ```typescript + * // Derive a wallet from a bip38 Mnemonic + * const wallet = Wallet.fromMnemonic( + * 'jewel insect retreat jump claim horse second chef west gossip bone frown exotic embark laundry' + * ) + * console.log(wallet) + * // Wallet { + * // publicKey: '02348F89E9A6A3615BA317F8474A3F51D66221562D3CA32BFA8D21348FF67012B2', + * // privateKey: '00A8F2E77FC0E05890C1B5088AFE0ECF9D96466A4419B897B1AB383E336E1735A2', + * // classicAddress: 'rwZiksrExmVkR64pf87Jor4cYbmff47SUm', + * // seed: undefined + * // }. + * + * // Derive a wallet from a base58 encoded seed. + * const seedWallet = Wallet.fromSeed('ssZkdwURFMBXenJPbrpE14b6noJSu') + * console.log(seedWallet) + * // Wallet { + * // publicKey: '02FE9932A9C4AA2AC9F0ED0F2B89302DE7C2C95F91D782DA3CF06E64E1C1216449', + * // privateKey: '00445D0A16DD05EFAF6D5AF45E6B8A6DE4170D93C0627021A0B8E705786CBCCFF7', + * // classicAddress: 'rG88FVLjvYiQaGftSa1cKuE2qNx7aK5ivo', + * // seed: 'ssZkdwURFMBXenJPbrpE14b6noJSu' + * // }. + * + * // Sign a JSON Transaction + * const signed = seedWallet.signTransaction({ + * TransactionType: 'Payment', + * Account: 'rG88FVLjvYiQaGftSa1cKuE2qNx7aK5ivo' + * ........... + * }). + * + * console.log(signed) + * // '1200007321......B01BE1DFF3'. + * console.log(decode(signed)) + * // { + * // TransactionType: 'Payment', + * // SigningPubKey: '02FE9932A9C4AA2AC9F0ED0F2B89302DE7C2C95F91D782DA3CF06E64E1C1216449', + * // TxnSignature: '3045022100AAD......5B631ABD21171B61B07D304', + * // Account: 'rG88FVLjvYiQaGftSa1cKuE2qNx7aK5ivo' + * // ........... + * // } + * ``` + * + * @category Offline Signing */ class Wallet { public readonly publicKey: string @@ -279,8 +324,10 @@ class Wallet { const decoded = decode(serialized) const txCopy = { ...tx } - // ...And ensure it is equal to the original tx, except: - // - It must have a TxnSignature or Signers (multisign). + /* + * And ensure it is equal to the original tx, except: + * - It must have a TxnSignature or Signers (multisign). + */ if (!decoded.TxnSignature && !decoded.Signers) { throw new ValidationError( 'Serialized transaction must have a TxnSignature or Signers property', @@ -291,14 +338,18 @@ class Wallet { // - We know that the original tx did not have Signers, so if it exists, we should delete it: delete decoded.Signers - // - If SigningPubKey was not in the original tx, then we should delete it. - // But if it was in the original tx, then we should ensure that it has not been changed. + /* + * - If SigningPubKey was not in the original tx, then we should delete it. + * But if it was in the original tx, then we should ensure that it has not been changed. + */ if (!tx.SigningPubKey) { delete decoded.SigningPubKey } - // - Memos have exclusively hex data which should ignore case. - // Since decode goes to upper case, we set all tx memos to be uppercase for the comparison. + /* + * - Memos have exclusively hex data which should ignore case. + * Since decode goes to upper case, we set all tx memos to be uppercase for the comparison. + */ txCopy.Memos?.map((memo) => { const memoCopy = { ...memo } if (memo.Memo.MemoData) { diff --git a/src/wallet/signer.ts b/src/wallet/signer.ts index f3bc3c58..c74da4ba 100644 --- a/src/wallet/signer.ts +++ b/src/wallet/signer.ts @@ -35,9 +35,11 @@ function multisign(transactions: Array): string { transactions.forEach((txOrBlob) => { const tx: Transaction = getDecodedTransaction(txOrBlob) - // This will throw a more clear error for JS users if any of the supplied transactions has incorrect formatting - // TODO: Replace this with validate() (The general validation function for all Transactions) - // also make validate accept '| Transaction' to avoid type casting here. + /* + * This will throw a more clear error for JS users if any of the supplied transactions has incorrect formatting + * TODO: Replace this with validate() (The general validation function for all Transactions) + * also make validate accept '| Transaction' to avoid type casting here. + */ // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- validate does not accept Transaction type validateBaseTransaction(tx as unknown as Record) if (tx.Signers == null || tx.Signers.length === 0) { diff --git a/test/client.ts b/test/client.ts index adea6ad6..5f9664b1 100644 --- a/test/client.ts +++ b/test/client.ts @@ -25,8 +25,7 @@ describe('Client', function () { it('Client valid options', function () { const client = new Client('wss://s:1') - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- TODO: fix when src/client linting is merged - const privateConnectionUrl = (client.connection as any).url + const privateConnectionUrl = client.url assert.deepEqual(privateConnectionUrl, 'wss://s:1') }) @@ -35,7 +34,9 @@ describe('Client', function () { }) it('Client connect() times out after 2 seconds', function () { - // TODO: Use a timer mock like https://jestjs.io/docs/en/timer-mocks - // to test that connect() times out after 2 seconds. + /* + * TODO: Use a timer mock like https://jestjs.io/docs/en/timer-mocks + * to test that connect() times out after 2 seconds. + */ }) }) diff --git a/test/client/constructor.ts b/test/client/constructor.ts index de113409..74a23015 100644 --- a/test/client/constructor.ts +++ b/test/client/constructor.ts @@ -15,7 +15,7 @@ describe('client constructor', function () { it('Client valid options', function () { const client = new Client('wss://s:1') - const privateConnectionUrl = client.connection.getUrl() + const privateConnectionUrl = client.url assert.deepEqual(privateConnectionUrl, 'wss://s:1') }) diff --git a/test/client/errors.ts b/test/client/errors.ts index 94171447..3fc8ebe1 100644 --- a/test/client/errors.ts +++ b/test/client/errors.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { XrplError, NotFoundError } from '../../src' +import { XrplError, NotFoundError } from 'xrpl-local' + import { setupClient, teardownClient } from '../setupClient' describe('client errors', function () { diff --git a/test/client/getFee.ts b/test/client/getFee.ts index 84156624..5b5d821d 100644 --- a/test/client/getFee.ts +++ b/test/client/getFee.ts @@ -27,8 +27,11 @@ describe('client.getFee', function () { 'server_info', rippled.server_info.highLoadFactor, ) - // Ensure that overriding with high maxFeeXRP of '51540' causes no errors. - // (fee will actually be 51539.607552) + + /* + * Ensure that overriding with high maxFeeXRP of '51540' causes no errors. + * (fee will actually be 51539.607552) + */ this.client.maxFeeXRP = '51540' const fee = await this.client.getFee() assert.strictEqual(fee, '51539.607552') @@ -41,8 +44,10 @@ describe('client.getFee', function () { assert.strictEqual(fee, '0.000014') }) - // This is not recommended since it may result in attempting to pay - // less than the base fee. However, this test verifies the existing behavior. + /* + * This is not recommended since it may result in attempting to pay + * less than the base fee. However, this test verifies the existing behavior. + */ it('getFee cushion less than 1.0', async function () { this.mockRippled.addResponse('server_info', rippled.server_info.normal) this.client.feeCushion = 0.9 diff --git a/test/client/getOrderbook.ts b/test/client/getOrderbook.ts index c1ccdacd..795c227f 100644 --- a/test/client/getOrderbook.ts +++ b/test/client/getOrderbook.ts @@ -1,8 +1,9 @@ import BigNumber from 'bignumber.js' import { assert } from 'chai' -import { BookOffersRequest, ValidationError } from '../../src' -import { OfferFlags } from '../../src/models/ledger/offer' +import { BookOffersRequest, ValidationError } from 'xrpl-local' +import { OfferFlags } from 'xrpl-local/models/ledger/offer' + import requests from '../fixtures/requests' import responses from '../fixtures/responses' import rippled from '../fixtures/rippled' diff --git a/test/client/hasNextPage.ts b/test/client/hasNextPage.ts index 0212a1fa..4623a4bb 100644 --- a/test/client/hasNextPage.ts +++ b/test/client/hasNextPage.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { Client } from '../../src' +import { Client } from 'xrpl-local' + import rippled from '../fixtures/rippled' import { setupClient, teardownClient } from '../setupClient' diff --git a/test/client/partialPayments.ts b/test/client/partialPayments.ts index 1ce3bf73..e22e8bfc 100644 --- a/test/client/partialPayments.ts +++ b/test/client/partialPayments.ts @@ -1,7 +1,8 @@ /* eslint-disable @typescript-eslint/no-explicit-any -- required for formatting transactions */ import { expect } from 'chai' -import type { TransactionStream } from '../../src' +import type { TransactionStream } from 'xrpl-local' + import rippled from '../fixtures/rippled' import { setupClient, teardownClient } from '../setupClient' diff --git a/test/client/requestNextPage.ts b/test/client/requestNextPage.ts index fce9a578..d3a4e9cd 100644 --- a/test/client/requestNextPage.ts +++ b/test/client/requestNextPage.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { Client } from '../../src' +import { Client } from 'xrpl-local' + import rippled from '../fixtures/rippled' import { setupClient, teardownClient } from '../setupClient' import { assertRejects } from '../testUtils' diff --git a/test/connection.ts b/test/connection.ts index 1fc61f48..0ece9ceb 100644 --- a/test/connection.ts +++ b/test/connection.ts @@ -244,8 +244,10 @@ describe('Connection', function () { }) it('DisconnectedError on initial onOpen send', async function () { - // onOpen previously could throw PromiseRejectionHandledWarning: Promise rejection was handled asynchronously - // do not rely on the client.setup hook to test this as it bypasses the case, disconnect client connection first + /* + * onOpen previously could throw PromiseRejectionHandledWarning: Promise rejection was handled asynchronously + * do not rely on the client.setup hook to test this as it bypasses the case, disconnect client connection first + */ await this.client.disconnect() // stub _onOpen to only run logic relevant to test case @@ -560,8 +562,10 @@ describe('Connection', function () { }) it('unrecognized message type', function (done) { - // This enables us to automatically support any - // new messages added by rippled in the future. + /* + * This enables us to automatically support any + * new messages added by rippled in the future. + */ this.client.connection.on('unknown', (event) => { assert.deepEqual(event, { type: 'unknown' }) done() @@ -570,23 +574,25 @@ describe('Connection', function () { this.client.connection.onMessage(JSON.stringify({ type: 'unknown' })) }) - // it('should clean up websocket connection if error after websocket is opened', async function () { - // await this.client.disconnect() - // // fail on connection - // this.client.connection.subscribeToLedger = async () => { - // throw new Error('error on _subscribeToLedger') - // } - // try { - // await this.client.connect() - // throw new Error('expected connect() to reject, but it resolved') - // } catch (err) { - // assert(err.message === 'error on _subscribeToLedger') - // // _ws.close event listener should have cleaned up the socket when disconnect _ws.close is run on connection error - // // do not fail on connection anymore - // this.client.connection.subscribeToLedger = async () => {} - // await this.client.connection.reconnect() - // } - // }) + /* + * it('should clean up websocket connection if error after websocket is opened', async function () { + * await this.client.disconnect() + * // fail on connection + * this.client.connection.subscribeToLedger = async () => { + * throw new Error('error on _subscribeToLedger') + * } + * try { + * await this.client.connect() + * throw new Error('expected connect() to reject, but it resolved') + * } catch (err) { + * assert(err.message === 'error on _subscribeToLedger') + * // _ws.close event listener should have cleaned up the socket when disconnect _ws.close is run on connection error + * // do not fail on connection anymore + * this.client.connection.subscribeToLedger = async () => {} + * await this.client.connection.reconnect() + * } + * }) + */ it('should try to reconnect on empty subscribe response on reconnect', function (done) { this.timeout(23000) diff --git a/test/mockRippled.ts b/test/mockRippled.ts index 866bf45e..d9d70056 100644 --- a/test/mockRippled.ts +++ b/test/mockRippled.ts @@ -42,8 +42,10 @@ export interface PortResponse extends BaseResponse { } } -// We mock out WebSocketServer in these tests and add a lot of custom -// properties not defined on the normal WebSocketServer object. +/* + * We mock out WebSocketServer in these tests and add a lot of custom + * properties not defined on the normal WebSocketServer object. + */ // eslint-disable-next-line @typescript-eslint/no-explicit-any -- typing is too complicated otherwise type MockedWebSocketServer = any @@ -102,9 +104,11 @@ export default function createMockRippled(port: number): MockedWebSocketServer { }) }) - // Adds a mocked response - // If an object is passed in for `response`, then the response is static for the command - // If a function is passed in for `response`, then the response can be determined by the exact request shape + /* + * Adds a mocked response + * If an object is passed in for `response`, then the response is static for the command + * If a function is passed in for `response`, then the response can be determined by the exact request shape + */ mock.addResponse = function ( command: string, response: diff --git a/test/models/accountDelete.ts b/test/models/accountDelete.ts index 12a76d53..da528a7c 100644 --- a/test/models/accountDelete.ts +++ b/test/models/accountDelete.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateAccountDelete, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateAccountDelete } from 'xrpl-local/models/transactions/accountDelete' /** * AccountDelete Transaction Verification Testing. diff --git a/test/models/accountSet.ts b/test/models/accountSet.ts index 1da698d5..cd274666 100644 --- a/test/models/accountSet.ts +++ b/test/models/accountSet.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateAccountSet, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateAccountSet } from 'xrpl-local/models/transactions/accountSet' /** * AccountSet Transaction Verification Testing. diff --git a/test/models/checkCancel.ts b/test/models/checkCancel.ts index 54cac038..0f41a63d 100644 --- a/test/models/checkCancel.ts +++ b/test/models/checkCancel.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateCheckCancel, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateCheckCancel } from 'xrpl-local/models/transactions/checkCancel' /** * CheckCancel Transaction Verification Testing. diff --git a/test/models/checkCash.ts b/test/models/checkCash.ts index 061b2330..48d683e6 100644 --- a/test/models/checkCash.ts +++ b/test/models/checkCash.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateCheckCash, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateCheckCash } from 'xrpl-local/models/transactions/checkCash' /** * CheckCash Transaction Verification Testing. diff --git a/test/models/checkCreate.ts b/test/models/checkCreate.ts index 4c4d58fe..2fda35d3 100644 --- a/test/models/checkCreate.ts +++ b/test/models/checkCreate.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateCheckCreate, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateCheckCreate } from 'xrpl-local/models/transactions/checkCreate' /** * CheckCreate Transaction Verification Testing. diff --git a/test/models/depositPreauth.ts b/test/models/depositPreauth.ts index d39a4a9c..e3a44ff2 100644 --- a/test/models/depositPreauth.ts +++ b/test/models/depositPreauth.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateDepositPreauth, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateDepositPreauth } from 'xrpl-local/models/transactions/depositPreauth' /** * DepositPreauth Transaction Verification Testing. diff --git a/test/models/escrowCancel.ts b/test/models/escrowCancel.ts index 4d60dfc9..9889ed71 100644 --- a/test/models/escrowCancel.ts +++ b/test/models/escrowCancel.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateEscrowCancel, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateEscrowCancel } from 'xrpl-local/models/transactions/escrowCancel' /** * Transaction Verification Testing. diff --git a/test/models/escrowCreate.ts b/test/models/escrowCreate.ts index ece97f20..a9ae1997 100644 --- a/test/models/escrowCreate.ts +++ b/test/models/escrowCreate.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateEscrowCreate, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateEscrowCreate } from 'xrpl-local/models/transactions/escrowCreate' /** * EscrowCreate Transaction Verification Testing. diff --git a/test/models/escrowFinish.ts b/test/models/escrowFinish.ts index 78bc2fb5..09ba2303 100644 --- a/test/models/escrowFinish.ts +++ b/test/models/escrowFinish.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateEscrowFinish, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateEscrowFinish } from 'xrpl-local/models/transactions/escrowFinish' /** * EscrowFinish Transaction Verification Testing. diff --git a/test/models/offerCancel.ts b/test/models/offerCancel.ts index f7d631cc..eee15591 100644 --- a/test/models/offerCancel.ts +++ b/test/models/offerCancel.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateOfferCancel, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateOfferCancel } from 'xrpl-local/models/transactions/offerCancel' /** * OfferCancel Transaction Verification Testing. diff --git a/test/models/offerCreate.ts b/test/models/offerCreate.ts index cae201f4..a887d8b6 100644 --- a/test/models/offerCreate.ts +++ b/test/models/offerCreate.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateOfferCreate, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateOfferCreate } from 'xrpl-local/models/transactions/offerCreate' /** * OfferCreate Transaction Verification Testing. diff --git a/test/models/payment.ts b/test/models/payment.ts index 36f9d5b6..4bc52da0 100644 --- a/test/models/payment.ts +++ b/test/models/payment.ts @@ -1,11 +1,7 @@ import { assert } from 'chai' -import { - validatePayment, - validate, - PaymentFlags, - ValidationError, -} from 'xrpl-local' +import { validate, PaymentFlags, ValidationError } from 'xrpl-local' +import { validatePayment } from 'xrpl-local/models/transactions/payment' /** * PaymentTransaction Verification Testing. diff --git a/test/models/paymentChannelClaim.ts b/test/models/paymentChannelClaim.ts index 760049c3..99780981 100644 --- a/test/models/paymentChannelClaim.ts +++ b/test/models/paymentChannelClaim.ts @@ -1,10 +1,7 @@ import { assert } from 'chai' -import { - validatePaymentChannelClaim, - validate, - ValidationError, -} from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validatePaymentChannelClaim } from 'xrpl-local/models/transactions/paymentChannelClaim' /** * PaymentChannelClaim Transaction Verification Testing. diff --git a/test/models/paymentChannelCreate.ts b/test/models/paymentChannelCreate.ts index 9a7877a0..9c771df9 100644 --- a/test/models/paymentChannelCreate.ts +++ b/test/models/paymentChannelCreate.ts @@ -1,10 +1,7 @@ import { assert } from 'chai' -import { - validatePaymentChannelCreate, - validate, - ValidationError, -} from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validatePaymentChannelCreate } from 'xrpl-local/models/transactions/paymentChannelCreate' /** * PaymentChannelCreate Transaction Verification Testing. diff --git a/test/models/paymentChannelFund.ts b/test/models/paymentChannelFund.ts index a0b06a0a..8f139971 100644 --- a/test/models/paymentChannelFund.ts +++ b/test/models/paymentChannelFund.ts @@ -1,10 +1,7 @@ import { assert } from 'chai' -import { - validatePaymentChannelFund, - validate, - ValidationError, -} from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validatePaymentChannelFund } from 'xrpl-local/models/transactions/paymentChannelFund' /** * PaymentChannelFund Transaction Verification Testing. diff --git a/test/models/setRegularKey.ts b/test/models/setRegularKey.ts index 7b5fa407..c6612045 100644 --- a/test/models/setRegularKey.ts +++ b/test/models/setRegularKey.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validate, validateSetRegularKey, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateSetRegularKey } from 'xrpl-local/models/transactions/setRegularKey' /** * SetRegularKey Transaction Verification Testing. diff --git a/test/models/signerListSet.ts b/test/models/signerListSet.ts index 6c19bfe6..408b7ceb 100644 --- a/test/models/signerListSet.ts +++ b/test/models/signerListSet.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validate, validateSignerListSet, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateSignerListSet } from 'xrpl-local/models/transactions/signerListSet' /** * SignerListSet Transaction Verification Testing. diff --git a/test/models/ticketCreate.ts b/test/models/ticketCreate.ts index de1c4030..700dd4c0 100644 --- a/test/models/ticketCreate.ts +++ b/test/models/ticketCreate.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateTicketCreate, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateTicketCreate } from 'xrpl-local/models/transactions/ticketCreate' /** * TicketCreate Transaction Verification Testing. diff --git a/test/models/trustSet.ts b/test/models/trustSet.ts index 4c02aa34..39183576 100644 --- a/test/models/trustSet.ts +++ b/test/models/trustSet.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { validateTrustSet, validate, ValidationError } from 'xrpl-local' +import { validate, ValidationError } from 'xrpl-local' +import { validateTrustSet } from 'xrpl-local/models/transactions/trustSet' /** * TrustSet Transaction Verification Testing. diff --git a/test/runClientTests.ts b/test/runClientTests.ts index d4cc01b6..7f67febe 100644 --- a/test/runClientTests.ts +++ b/test/runClientTests.ts @@ -12,8 +12,10 @@ import { Client } from 'xrpl-local' */ describe('Client', function () { - // doesn't need a functional client, just needs to instantiate to get a list of public methods - // (to determine what methods are missing from ) + /* + * Doesn't need a functional client, just needs to instantiate to get a list of public methods + * (to determine what methods are missing from ) + */ const allPublicMethods = getAllPublicMethods(new Client('wss://')) diff --git a/test/utils/dropsToXrp.ts b/test/utils/dropsToXrp.ts index a53b9514..4c1c6343 100644 --- a/test/utils/dropsToXrp.ts +++ b/test/utils/dropsToXrp.ts @@ -1,7 +1,7 @@ import BigNumber from 'bignumber.js' import { assert } from 'chai' -import { dropsToXrp } from '../../src/utils' +import { dropsToXrp } from 'xrpl-local/utils' describe('dropsToXrp', function () { it('works with a typical amount', function () { diff --git a/test/utils/generateAddress.ts b/test/utils/generateAddress.ts index 396a6f55..e41d56c5 100644 --- a/test/utils/generateAddress.ts +++ b/test/utils/generateAddress.ts @@ -1,19 +1,14 @@ import { assert } from 'chai' import { UnexpectedError } from 'xrpl-local' +import ECDSA from 'xrpl-local/ecdsa' +import { generateXAddress } from 'xrpl-local/utils/generateAddress' -import ECDSA from '../../src/ecdsa' -import { - generateXAddress, - GenerateAddressOptions, -} from '../../src/utils/generateAddress' import responses from '../fixtures/responses' describe('generateAddress', function () { it('generateAddress', function () { assert.deepEqual( - // GIVEN entropy of all zeros - // WHEN generating an address generateXAddress({ entropy: new Array(16).fill(0) }), // THEN we get the expected return value @@ -23,12 +18,16 @@ describe('generateAddress', function () { it('generateAddress invalid entropy', function () { assert.throws(() => { - // GIVEN entropy of 1 byte - // WHEN generating an address + /* + * GIVEN entropy of 1 byte + * WHEN generating an address + */ generateXAddress({ entropy: new Array(1).fill(0) }) - // THEN an UnexpectedError is thrown - // because 16 bytes of entropy are required + /* + * THEN an UnexpectedError is thrown + * because 16 bytes of entropy are required + */ }, UnexpectedError) }) @@ -57,7 +56,7 @@ describe('generateAddress', function () { it('generateAddress with algorithm `ecdsa-secp256k1`', function () { // GIVEN we want to use 'ecdsa-secp256k1' - const options: GenerateAddressOptions = { + const options = { algorithm: ECDSA.secp256k1, includeClassicAddress: true, } @@ -84,7 +83,7 @@ describe('generateAddress', function () { it('generateAddress with algorithm `ed25519`', function () { // GIVEN we want to use 'ed25519' - const options: GenerateAddressOptions = { + const options = { algorithm: ECDSA.ed25519, includeClassicAddress: true, } @@ -106,7 +105,7 @@ describe('generateAddress', function () { it('generateAddress with algorithm `ecdsa-secp256k1` and given entropy', function () { // GIVEN we want to use 'ecdsa-secp256k1' with entropy of zero - const options: GenerateAddressOptions = { + const options = { algorithm: ECDSA.secp256k1, entropy: new Array(16).fill(0), } @@ -120,7 +119,7 @@ describe('generateAddress', function () { it('generateAddress with algorithm `ed25519` and given entropy', function () { // GIVEN we want to use 'ed25519' with entropy of zero - const options: GenerateAddressOptions = { + const options = { algorithm: ECDSA.ed25519, entropy: new Array(16).fill(0), } @@ -138,7 +137,7 @@ describe('generateAddress', function () { it('generateAddress with algorithm `ecdsa-secp256k1` and given entropy; include classic address', function () { // GIVEN we want to use 'ecdsa-secp256k1' with entropy of zero - const options: GenerateAddressOptions = { + const options = { algorithm: ECDSA.secp256k1, entropy: new Array(16).fill(0), includeClassicAddress: true, @@ -153,7 +152,7 @@ describe('generateAddress', function () { it('generateAddress with algorithm `ed25519` and given entropy; include classic address', function () { // GIVEN we want to use 'ed25519' with entropy of zero - const options: GenerateAddressOptions = { + const options = { algorithm: ECDSA.ed25519, entropy: new Array(16).fill(0), includeClassicAddress: true, @@ -174,7 +173,7 @@ describe('generateAddress', function () { it('generateAddress with algorithm `ecdsa-secp256k1` and given entropy; include classic address; for test network use', function () { // GIVEN we want to use 'ecdsa-secp256k1' with entropy of zero - const options: GenerateAddressOptions = { + const options = { algorithm: ECDSA.secp256k1, entropy: new Array(16).fill(0), includeClassicAddress: true, @@ -195,7 +194,7 @@ describe('generateAddress', function () { it('generateAddress with algorithm `ed25519` and given entropy; include classic address; for test network use', function () { // GIVEN we want to use 'ed25519' with entropy of zero - const options: GenerateAddressOptions = { + const options = { algorithm: ECDSA.ed25519, entropy: new Array(16).fill(0), includeClassicAddress: true, @@ -216,7 +215,7 @@ describe('generateAddress', function () { it('generateAddress for test network use', function () { // GIVEN we want an address for test network use - const options: GenerateAddressOptions = { test: true } + const options = { test: true } // WHEN generating an address const account = generateXAddress(options) diff --git a/test/utils/getBalanceChanges.ts b/test/utils/getBalanceChanges.ts index d78df840..65561b80 100644 --- a/test/utils/getBalanceChanges.ts +++ b/test/utils/getBalanceChanges.ts @@ -1,6 +1,7 @@ import { assert } from 'chai' -import { getBalanceChanges } from '../../src/utils' +import { getBalanceChanges } from 'xrpl-local/utils' + import paymentToken from '../fixtures/utils/paymentToken.json' import paymentTokenDestinationNoBalance from '../fixtures/utils/paymentTokenDestinationNoBalance.json' import paymentTokenMultipath from '../fixtures/utils/paymentTokenMultipath.json' diff --git a/test/utils/hashLedger.ts b/test/utils/hashLedger.ts index c4e4bb3d..9312022b 100644 --- a/test/utils/hashLedger.ts +++ b/test/utils/hashLedger.ts @@ -1,8 +1,8 @@ import { assert } from 'chai' import { ValidationError, XrplError } from 'xrpl-local' +import { hashes } from 'xrpl-local/utils' -import { hashes } from '../../src/utils' import requests from '../fixtures/requests' import responses from '../fixtures/responses' diff --git a/test/utils/hashes.ts b/test/utils/hashes.ts index 35bb8cb3..b6c3e0a6 100644 --- a/test/utils/hashes.ts +++ b/test/utils/hashes.ts @@ -5,7 +5,6 @@ import { assert } from 'chai' import { encode } from 'ripple-binary-codec' import { OfferCreate, Transaction, ValidationError } from 'xrpl-local' - import { hashStateTree, hashTxTree, @@ -16,7 +15,8 @@ import { hashAccountRoot, hashOfferId, hashSignerListId, -} from '../../src/utils/hashes' +} from 'xrpl-local/utils/hashes' + import fixtures from '../fixtures/rippled' import { assertResultMatch } from '../testUtils' diff --git a/test/utils/signPaymentChannelClaim.ts b/test/utils/signPaymentChannelClaim.ts index 111af7cc..666c8475 100644 --- a/test/utils/signPaymentChannelClaim.ts +++ b/test/utils/signPaymentChannelClaim.ts @@ -1,4 +1,5 @@ -import signPaymentChannelClaim from '../../src/utils/signPaymentChannelClaim' +import signPaymentChannelClaim from 'xrpl-local/utils/signPaymentChannelClaim' + import responses from '../fixtures/responses' import { assertResultMatch } from '../testUtils' diff --git a/test/utils/verifyPaymentChannelClaim.ts b/test/utils/verifyPaymentChannelClaim.ts index 7506d8ff..a14928a1 100644 --- a/test/utils/verifyPaymentChannelClaim.ts +++ b/test/utils/verifyPaymentChannelClaim.ts @@ -1,4 +1,5 @@ -import { verifyPaymentChannelClaim } from '../../src' +import { verifyPaymentChannelClaim } from 'xrpl-local' + import requests from '../fixtures/requests' import responses from '../fixtures/responses' import { assertResultMatch } from '../testUtils' diff --git a/test/utils/xrpToDrops.ts b/test/utils/xrpToDrops.ts index 93b67aa3..85ac4d62 100644 --- a/test/utils/xrpToDrops.ts +++ b/test/utils/xrpToDrops.ts @@ -1,7 +1,7 @@ import BigNumber from 'bignumber.js' import { assert } from 'chai' -import { xrpToDrops } from '../../src/utils' +import { xrpToDrops } from 'xrpl-local/utils' describe('xrpToDrops', function () { it('works with a typical amount', function () { diff --git a/test/wallet/signer.ts b/test/wallet/signer.ts index 2b2f4552..e2720380 100644 --- a/test/wallet/signer.ts +++ b/test/wallet/signer.ts @@ -10,8 +10,6 @@ import { verifySignature, } from 'xrpl-local/wallet/signer' -import { SignedTxBlobHash } from '../../src/wallet' - const publicKey = '030E58CDD076E798C84755590AAF6237CA8FAE821070A59F648B517A30DC6F589D' const privateKey = @@ -181,7 +179,7 @@ describe('Signer', function () { hash: 'F73E975C70497A3DA61ADB76A3B39CD971A2DE017419A690BFAD6733B5FD8B3B', } - const signedTx: SignedTxBlobHash = wallet.sign(tx3) + const signedTx = wallet.sign(tx3) assert.deepEqual(signedTx, signedTxResponse) }) diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 00000000..0272dc82 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,17 @@ +{ + "entryPoints": ["./src/index.ts"], + "out": "./docs", + "categoryOrder": [ + "Constructor", + "Clients", + "Transaction Models", + "Transaction Flags", + "Ledger Flags", + "Utilities", + "Requests", + "Responses", + "Flags", + "Errors" + ], + "categorizeByGroup": false +}