ARCHIVE/xahau.js
1
0
Fork 0
mirror of https://github.com/Xahau/xahau.js.git synced 2025-11-20 04:05:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
docs: Adds JSDoc comments to all functions and interfaces
This commit is contained in:
Nathan Nichols
2021-10-12 12:04:18 -07:00
committed by GitHub
parent df4c9dc2fd
commit 615504db22
136 changed files with 3869 additions and 501 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
.eslintrc.js
View File

@@ -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: [
{

18
README.md
View File

@@ -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/`.

2
package.json
View File

@@ -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",

16
snippets/src/decoder.ts
View File

@@ -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))

38
snippets/src/getTransaction.ts
View File

@@ -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)
* }
*/

36
snippets/src/parseAccountFlags.ts
View File

@@ -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)
* }
*/

100
snippets/src/paths.ts
View File

@@ -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()
* }
*/

280
snippets/src/reliableTransactionSubmission.ts
View File

@@ -47,125 +47,139 @@
// */
// const payments = []
// const sourceAccount = (await generateTestnetAccount()).account
// console.log(
// `Generated new Testnet account: ${sourceAccount.classicAddress}/${sourceAccount.secret}`
// )
// // Send amounts from 1 drop to 10 drops
// for (let i = 1; i <= 10; i++) {
// payments.push({
// source: sourceAccount,
// destination: 'rhsoCozhUxwcyQgzFi1FVRoMVQgk7cZd4L', // Random Testnet destination
// amount_drops: i.toString()
// })
// }
// const results = await performPayments(payments)
// console.log(JSON.stringify(results, null, 2))
// process.exit(0)
// }
/*
* const sourceAccount = (await generateTestnetAccount()).account
* console.log(
* `Generated new Testnet account: ${sourceAccount.classicAddress}/${sourceAccount.secret}`
* )
* // Send amounts from 1 drop to 10 drops
* for (let i = 1; i <= 10; i++) {
* payments.push({
* source: sourceAccount,
* destination: 'rhsoCozhUxwcyQgzFi1FVRoMVQgk7cZd4L', // Random Testnet destination
* amount_drops: i.toString()
* })
* }
* const results = await performPayments(payments)
* console.log(JSON.stringify(results, null, 2))
* process.exit(0)
* }
*/
// async function performPayments(payments) {
// const finalResults = []
// const txFinalizedPromises = []
// const client = new Client('wss://s.altnet.rippletest.net:51233')
// await client.connect()
/*
* async function performPayments(payments) {
* const finalResults = []
* const txFinalizedPromises = []
* const client = new Client('wss://s.altnet.rippletest.net:51233')
* await client.connect()
*/
// for (let i = 0; i < payments.length; i++) {
// const payment = payments[i]
// const account_info: AccountInfoResponse = await client.request({
// command: 'account_info',
// account: payment.source.classicAddress,
// ledger_index: 'current'
// })
// const sequence = account_info.result.account_data.Sequence
// const preparedPayment = await client.preparePayment(
// payment.source.classicAddress,
// {
// source: {
// address: payment.source.classicAddress,
// amount: {
// value: payment.amount_drops,
// currency: 'drops'
// }
// },
// destination: {
// address: payment.destination,
// minAmount: {
// value: payment.amount_drops,
// currency: 'drops'
// }
// }
// },
// {
// sequence
// }
// )
// const signed = client.sign(preparedPayment.txJSON, payment.source.secret)
// finalResults.push({
// id: signed.id
// })
// const response = await client.request({
// command: 'submit',
// tx_blob: signed.signedTransaction
// })
/*
* for (let i = 0; i < payments.length; i++) {
* const payment = payments[i]
* const account_info: AccountInfoResponse = await client.request({
* command: 'account_info',
* account: payment.source.classicAddress,
* ledger_index: 'current'
* })
* const sequence = account_info.result.account_data.Sequence
* const preparedPayment = await client.preparePayment(
* payment.source.classicAddress,
* {
* source: {
* address: payment.source.classicAddress,
* amount: {
* value: payment.amount_drops,
* currency: 'drops'
* }
* },
* destination: {
* address: payment.destination,
* minAmount: {
* value: payment.amount_drops,
* currency: 'drops'
* }
* }
* },
* {
* sequence
* }
* )
* const signed = client.sign(preparedPayment.txJSON, payment.source.secret)
* finalResults.push({
* id: signed.id
* })
* const response = await client.request({
* command: 'submit',
* tx_blob: signed.signedTransaction
* })
*/
// // Most of the time we'll get 'tesSUCCESS' or (after many submissions) 'terQUEUED'
// console.log(`tx ${i} - tentative: ${response.result.engine_result}`)
/*
* // Most of the time we'll get 'tesSUCCESS' or (after many submissions) 'terQUEUED'
* console.log(`tx ${i} - tentative: ${response.result.engine_result}`)
*/
// const txFinalizedPromise = new Promise<void>((resolve) => {
// const ledgerClosedCallback = async (event: LedgerClosedEvent) => {
// let status
// try {
// status = await client.request({command: 'tx', transaction: signed.id})
// } catch (e) {
// // Typical error when the tx hasn't been validated yet:
// if (e.name !== 'MissingLedgerHistoryError') {
// console.log(e)
// }
/*
* const txFinalizedPromise = new Promise<void>((resolve) => {
* const ledgerClosedCallback = async (event: LedgerClosedEvent) => {
* let status
* try {
* status = await client.request({command: 'tx', transaction: signed.id})
* } catch (e) {
* // Typical error when the tx hasn't been validated yet:
* if (e.name !== 'MissingLedgerHistoryError') {
* console.log(e)
* }
*/
// if (
// event.ledger_index >
// preparedPayment.instructions.maxLedgerVersion + 3
// ) {
// // Assumptions:
// // - We are still connected to the same rippled server
// // - No ledger gaps occurred
// // - All ledgers between the time we submitted the tx and now have been checked for the tx
// status = {
// finalResult:
// 'Transaction was not, and never will be, included in a validated ledger'
// }
// } else {
// // Check again later:
// client.connection.once('ledgerClosed', ledgerClosedCallback)
// return
// }
// }
/*
* if (
* event.ledger_index >
* preparedPayment.instructions.maxLedgerVersion + 3
* ) {
* // Assumptions:
* // - We are still connected to the same rippled server
* // - No ledger gaps occurred
* // - All ledgers between the time we submitted the tx and now have been checked for the tx
* status = {
* finalResult:
* 'Transaction was not, and never will be, included in a validated ledger'
* }
* } else {
* // Check again later:
* client.connection.once('ledgerClosed', ledgerClosedCallback)
* return
* }
* }
*/
// for (let j = 0; j < finalResults.length; j++) {
// if (finalResults[j].id === signed.id) {
// finalResults[j].result = status.address
// ? {
// source: status.address,
// destination: status.specification.destination.address,
// deliveredAmount: status.outcome.deliveredAmount,
// result: status.outcome.result,
// timestamp: status.outcome.timestamp,
// ledgerVersion: status.outcome.ledgerVersion
// }
// : status
// process.stdout.write('.')
// return resolve()
// }
// }
// }
// client.connection.once('ledgerClosed', ledgerClosedCallback)
// })
// txFinalizedPromises.push(txFinalizedPromise)
// }
// await Promise.all(txFinalizedPromises)
// return finalResults
// }
/*
* for (let j = 0; j < finalResults.length; j++) {
* if (finalResults[j].id === signed.id) {
* finalResults[j].result = status.address
* ? {
* source: status.address,
* destination: status.specification.destination.address,
* deliveredAmount: status.outcome.deliveredAmount,
* result: status.outcome.result,
* timestamp: status.outcome.timestamp,
* ledgerVersion: status.outcome.ledgerVersion
* }
* : status
* process.stdout.write('.')
* return resolve()
* }
* }
* }
* client.connection.once('ledgerClosed', ledgerClosedCallback)
* })
* txFinalizedPromises.push(txFinalizedPromise)
* }
* await Promise.all(txFinalizedPromises)
* return finalResults
* }
*/
// /**
// * Generate a new Testnet account by requesting one from the faucet.
@@ -194,22 +208,24 @@
// response.on('end', () => {
// const body = Buffer.concat(chunks).toString()
// // "application/json; charset=utf-8"
// if (response.headers['content-type'].startsWith('application/json')) {
// resolve(JSON.parse(body))
// } else {
// reject({
// statusCode: response.statusCode,
// contentType: response.headers['content-type'],
// body
// })
// }
// })
// })
// request.on('error', (error) => {
// console.error(error)
// reject(error)
// })
// request.end()
// })
// }
/*
* // "application/json; charset=utf-8"
* if (response.headers['content-type'].startsWith('application/json')) {
* resolve(JSON.parse(body))
* } else {
* reject({
* statusCode: response.statusCode,
* contentType: response.headers['content-type'],
* body
* })
* }
* })
* })
* request.on('error', (error) => {
* console.error(error)
* reject(error)
* })
* request.end()
* })
* }
*/

24
src/client/backoff.ts
View File

@@ -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.

2
src/client/broadcastClient.ts
View File

@@ -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[]

44
src/client/connection.ts
View File

@@ -45,11 +45,11 @@ interface ConnectionOptions {
*/
export type ConnectionUserOptions = Partial<ConnectionOptions>
//
// 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<void> {
// 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

156
src/client/index.ts
View File

@@ -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<AccountChannelsResponse>
@@ -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<R extends Request, T extends Response>(
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<AccountChannelsResponse[]>
@@ -456,14 +514,18 @@ class Client extends EventEmitter {
request: T,
collect?: string,
): Promise<U[]> {
// 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<void> {
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<void> {
// 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
}

2
src/client/partialPayment.ts
View File

@@ -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)) {

6
src/client/requestManager.ts
View File

@@ -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()

67
src/errors.ts
View File

@@ -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,
}

55
src/models/ledger/accountRoot.ts
View File

@@ -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
}

24
src/models/ledger/amendments.ts
View File

@@ -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
}

50
src/models/ledger/check.ts
View File

@@ -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
}

24
src/models/ledger/depositPreauth.ts
View File

@@ -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
}

31
src/models/ledger/directoryNode.ts
View File

@@ -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
}

56
src/models/ledger/escrow.ts
View File

@@ -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
}

17
src/models/ledger/feeSettings.ts
View File

@@ -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
}

45
src/models/ledger/ledger.ts
View File

@@ -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<Transaction & { metaData?: TransactionMetadata }>
}

16
src/models/ledger/ledgerHashes.ts
View File

@@ -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
}

17
src/models/ledger/negativeUNL.ts
View File

@@ -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
}

29
src/models/ledger/offer.ts
View File

@@ -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
}

87
src/models/ledger/payChannel.ts
View File

@@ -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
}

55
src/models/ledger/rippleState.ts
View File

@@ -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
}

37
src/models/ledger/signerList.ts
View File

@@ -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
}

25
src/models/ledger/ticket.ts
View File

@@ -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
}

60
src/models/methods/accountChannels.ts
View File

@@ -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
}
}

32
src/models/methods/accountCurrencies.ts
View File

@@ -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
}
}

85
src/models/methods/accountInfo.ts
View File

@@ -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
}
}

104
src/models/methods/accountLines.ts
View File

@@ -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
}
}

68
src/models/methods/accountObjects.ts
View File

@@ -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
}
}

72
src/models/methods/accountOffers.ts
View File

@@ -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
}
}

76
src/models/methods/accountTx.ts
View File

@@ -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
}
}

13
src/models/methods/baseMethod.ts
View File

@@ -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'

67
src/models/methods/bookOffers.ts
View File

@@ -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
}

26
src/models/methods/channelVerify.ts
View File

@@ -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
}
}

40
src/models/methods/depositAuthorized.ts
View File

@@ -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
}
}

64
src/models/methods/fee.ts
View File

@@ -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
}
}

63
src/models/methods/gatewayBalances.ts
View File

@@ -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
}
}

8
src/models/methods/index.ts
View File

@@ -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

75
src/models/methods/ledger.ts
View File

@@ -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<LedgerQueueData | string>
/**
* 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
}
}

20
src/models/methods/ledgerClosed.ts
View File

@@ -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

20
src/models/methods/ledgerCurrent.ts
View File

@@ -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
}
}

50
src/models/methods/ledgerData.ts
View File

@@ -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
}

95
src/models/methods/ledgerEntry.ts
View File

@@ -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
}

35
src/models/methods/manifest.ts
View File

@@ -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
}
}

61
src/models/methods/norippleCheck.ts
View File

@@ -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[]
}
}

67
src/models/methods/pathFind.ts
View File

@@ -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

12
src/models/methods/ping.ts
View File

@@ -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

12
src/models/methods/random.ts
View File

@@ -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

48
src/models/methods/ripplePathFind.ts
View File

@@ -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

150
src/models/methods/serverInfo.ts
View File

@@ -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<ServerState, StateAccounting>
/** 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
}
}

14
src/models/methods/serverState.ts
View File

@@ -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: {

66
src/models/methods/submit.ts
View File

@@ -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
}
}

32
src/models/methods/submitMultisigned.ts
View File

@@ -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 }
}
}

234
src/models/methods/subscribe.ts
View File

@@ -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<string, never> | 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

31
src/models/methods/transactionEntry.ts
View File

@@ -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
}
}

41
src/models/methods/tx.ts
View File

@@ -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
}

32
src/models/methods/unsubscribe.ts
View File

@@ -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<string, never>
}

16
src/models/transactions/accountDelete.ts
View File

@@ -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
}

68
src/models/transactions/accountSet.ts
View File

@@ -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
}

12
src/models/transactions/checkCancel.ts
View File

@@ -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
}

21
src/models/transactions/checkCash.ts
View File

@@ -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
}

27
src/models/transactions/checkCreate.ts
View File

@@ -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
}

58
src/models/transactions/common.ts
View File

@@ -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
}

12
src/models/transactions/depositPreauth.ts
View File

@@ -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
}

10
src/models/transactions/escrowCancel.ts
View File

@@ -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
}

29
src/models/transactions/escrowCreate.ts
View File

@@ -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
}

18
src/models/transactions/escrowFinish.ts
View File

@@ -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
}

44
src/models/transactions/index.ts
View File

@@ -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'

11
src/models/transactions/offerCancel.ts
View File

@@ -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
}

49
src/models/transactions/offerCreate.ts
View File

@@ -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
}

79
src/models/transactions/payment.ts
View File

@@ -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
}

74
src/models/transactions/paymentChannelClaim.ts
View File

@@ -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
}

36
src/models/transactions/paymentChannelCreate.ts
View File

@@ -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
}

25
src/models/transactions/paymentChannelFund.ts
View File

@@ -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
}

11
src/models/transactions/setRegularKey.ts
View File

@@ -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
}

17
src/models/transactions/signerListSet.ts
View File

@@ -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[]
}

11
src/models/transactions/ticketCreate.ts
View File

@@ -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
}

27
src/models/transactions/transaction.ts
View File

@@ -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<string, unknown>): void {
throw new ValidationError(`Invalid Transaction: ${tx.TransactionType}`)
}
}
export {
AccountSetAsfFlags,
AccountSetTfFlags,
OfferCreateFlags,
PaymentFlags,
PaymentChannelClaimFlags,
TrustSetFlags,
}

52
src/models/transactions/trustSet.ts
View File

@@ -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
}

6
src/sugar/autofill.ts
View File

@@ -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))
}

8
src/sugar/orderbook.ts
View File

@@ -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),

12
src/sugar/submit.ts
View File

@@ -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<void> {
@@ -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,

8
src/sugar/utils.ts
View File

@@ -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.',

8
src/utils/balanceChanges.ts
View File

@@ -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

10
src/utils/generateAddress.ts
View File

@@ -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.

1
src/utils/index.ts
View File

@@ -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 {

24
src/utils/xrpConversion.ts
View File

@@ -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 -` +

10
src/wallet/fundWallet.ts
View File

@@ -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 }

67
src/wallet/index.ts
View File

@@ -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) {

8
src/wallet/signer.ts
View File

@@ -35,9 +35,11 @@ function multisign(transactions: Array<Transaction | string>): 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<string, unknown>)
if (tx.Signers == null || tx.Signers.length === 0) {

9
test/client.ts
View File

@@ -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.
*/
})
})

2
test/client/constructor.ts
View File

@@ -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')
})

3
test/client/errors.ts
View File

@@ -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 () {

13
test/client/getFee.ts
View File

@@ -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

Some files were not shown because too many files have changed in this diff Show More