xrpl 2.9.1 → 2.11.0

package/src/sugar/balances.ts

@@ -0,0 +1,123 @@
+import flatMap from 'lodash/flatMap'
+
+import type { Balance, Client } from '..'
+import {
+  AccountLinesRequest,
+  AccountLinesTrustline,
+  LedgerIndex,
+  AccountInfoRequest,
+} from '../models'
+import { dropsToXrp } from '../utils'
+
+function formatBalances(trustlines: AccountLinesTrustline[]): Balance[] {
+  return trustlines.map((trustline) => ({
+    value: trustline.balance,
+    currency: trustline.currency,
+    issuer: trustline.account,
+  }))
+}
+
+/**
+ * Get the XRP balance for an account.
+ *
+ * @example
+ * ```ts
+ * const client = new Client(wss://s.altnet.rippletest.net:51233)
+ * const balance = await client.getXrpBalance('rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn')
+ * console.log(balance)
+ * /// '200'
+ * ```
+ *
+ * @param this - Client.
+ * @param address - Address of the account to retrieve XRP balance.
+ * @param options - Options to include for getting the XRP balance.
+ * @param options.ledger_index - Retrieve the account balances at a given
+ * ledger_index.
+ * @param options.ledger_hash - Retrieve the account balances at the ledger with
+ * a given ledger_hash.
+ * @returns The XRP balance of the account (as a string).
+ */
+async function getXrpBalance(
+  this: Client,
+  address: string,
+  options: {
+    ledger_hash?: string
+    ledger_index?: LedgerIndex
+  } = {},
+): Promise<string> {
+  const xrpRequest: AccountInfoRequest = {
+    command: 'account_info',
+    account: address,
+    ledger_index: options.ledger_index ?? 'validated',
+    ledger_hash: options.ledger_hash,
+  }
+  const response = await this.request(xrpRequest)
+  return dropsToXrp(response.result.account_data.Balance)
+}
+
+/**
+ * Get XRP/non-XRP balances for an account.
+ *
+ * @param this - Client.
+ * @param address - Address of the account to retrieve balances for.
+ * @param options - Allows the client to specify a ledger_hash, ledger_index,
+ * filter by peer, and/or limit number of balances.
+ * @param options.ledger_index - Retrieve the account balances at a given
+ * ledger_index.
+ * @param options.ledger_hash - Retrieve the account balances at the ledger with
+ * a given ledger_hash.
+ * @param options.peer - Filter balances by peer.
+ * @param options.limit - Limit number of balances to return.
+ * @returns An array of XRP/non-XRP balances for the given account.
+ */
+// eslint-disable-next-line max-lines-per-function -- Longer definition is required for end users to see the definition.
+async function getBalances(
+  this: Client,
+  address: string,
+  options: {
+    ledger_hash?: string
+    ledger_index?: LedgerIndex
+    peer?: string
+    limit?: number
+  } = {},
+): Promise<
+  Array<{ value: string; currency: string; issuer?: string | undefined }>
+> {
+  const balances: Balance[] = []
+
+  // get XRP balance
+  let xrpPromise: Promise<string> = Promise.resolve('')
+  if (!options.peer) {
+    xrpPromise = this.getXrpBalance(address, {
+      ledger_hash: options.ledger_hash,
+      ledger_index: options.ledger_index,
+    })
+  }
+
+  // get non-XRP balances
+  const linesRequest: AccountLinesRequest = {
+    command: 'account_lines',
+    account: address,
+    ledger_index: options.ledger_index ?? 'validated',
+    ledger_hash: options.ledger_hash,
+    peer: options.peer,
+    limit: options.limit,
+  }
+  const linesPromise = this.requestAll(linesRequest)
+
+  // combine results
+  await Promise.all([xrpPromise, linesPromise]).then(
+    ([xrpBalance, linesResponses]) => {
+      const accountLinesBalance = flatMap(linesResponses, (response) =>
+        formatBalances(response.result.lines),
+      )
+      if (xrpBalance !== '') {
+        balances.push({ currency: 'XRP', value: xrpBalance })
+      }
+      balances.push(...accountLinesBalance)
+    },
+  )
+  return balances.slice(0, options.limit)
+}
+
+export { getXrpBalance, getBalances }

package/src/sugar/getFeeXrp.ts

@@ -0,0 +1,45 @@
+import BigNumber from 'bignumber.js'
+
+import type { Client } from '..'
+import { XrplError } from '../errors'
+
+const NUM_DECIMAL_PLACES = 6
+const BASE_10 = 10
+
+/**
+ * Calculates the current transaction fee for the ledger.
+ * Note: This is a public API that can be called directly.
+ *
+ * @param client - The Client used to connect to the ledger.
+ * @param cushion - The fee cushion to use.
+ * @returns The transaction fee.
+ */
+export default async function getFeeXrp(
+  client: Client,
+  cushion?: number,
+): Promise<string> {
+  const feeCushion = cushion ?? client.feeCushion
+
+  const serverInfo = (await client.request({ command: 'server_info' })).result
+    .info
+
+  const baseFee = serverInfo.validated_ledger?.base_fee_xrp
+
+  if (baseFee == null) {
+    throw new XrplError(
+      'getFeeXrp: Could not get base_fee_xrp from server_info',
+    )
+  }
+
+  const baseFeeXrp = new BigNumber(baseFee)
+  if (serverInfo.load_factor == null) {
+    // https://github.com/ripple/rippled/issues/3812#issuecomment-816871100
+    serverInfo.load_factor = 1
+  }
+  let fee = baseFeeXrp.times(serverInfo.load_factor).times(feeCushion)
+
+  // Cap fee to `client.maxFeeXRP`
+  fee = BigNumber.min(fee, client.maxFeeXRP)
+  // Round fee to 6 decimal places
+  return new BigNumber(fee.toFixed(NUM_DECIMAL_PLACES)).toString(BASE_10)
+}

package/src/sugar/getLedgerIndex.ts

@@ -0,0 +1,15 @@
+import type { Client } from '..'
+
+/**
+ * Returns the index of the most recently validated ledger.
+ *
+ * @param this - The Client used to connect to the ledger.
+ * @returns The most recently validated ledger index.
+ */
+export default async function getLedgerIndex(this: Client): Promise<number> {
+  const ledgerResponse = await this.request({
+    command: 'ledger',
+    ledger_index: 'validated',
+  })
+  return ledgerResponse.result.ledger_index
+}

package/src/sugar/getOrderbook.ts

@@ -0,0 +1,152 @@
+/* eslint-disable max-lines-per-function -- Needs to process orderbooks. */
+import BigNumber from 'bignumber.js'
+import flatMap from 'lodash/flatMap'
+
+import type { Client } from '../client'
+import { ValidationError } from '../errors'
+import { LedgerIndex } from '../models/common'
+import { OfferFlags } from '../models/ledger/Offer'
+import {
+  BookOffer,
+  BookOfferCurrency,
+  BookOffersRequest,
+} from '../models/methods/bookOffers'
+
+const DEFAULT_LIMIT = 20
+
+function sortOffers(offers: BookOffer[]): BookOffer[] {
+  return offers.sort((offerA, offerB) => {
+    const qualityA = offerA.quality ?? 0
+    const qualityB = offerB.quality ?? 0
+
+    return new BigNumber(qualityA).comparedTo(qualityB)
+  })
+}
+
+const getOrderbookOptionsSet = new Set([
+  'limit',
+  'ledger_index',
+  'ledger_hash',
+  'taker',
+])
+
+/**
+ * Fetch orderbook (buy/sell orders) between two currency pairs. This checks both sides of the orderbook
+ * by making two `order_book` requests (with the second reversing takerPays and takerGets). Returned offers are
+ * not normalized in this function, so either currency could be takerGets or takerPays.
+ *
+ * @param this - Client.
+ * @param currency1 - Specification of one currency involved. (With a currency code and optionally an issuer)
+ * @param currency2 - Specification of a second currency involved. (With a currency code and optionally an issuer)
+ * @param options - Options allowing the client to specify ledger_index,
+ * ledger_hash, filter by taker, and/or limit number of orders.
+ * @param options.ledger_index - Retrieve the orderbook at a given ledger_index.
+ * @param options.ledger_hash - Retrieve the orderbook at the ledger with a
+ * given ledger_hash.
+ * @param options.taker - Filter orders by taker.
+ * @param options.limit - The limit passed into each book_offers request.
+ * Can return more than this due to two calls being made. Defaults to 20.
+ * @returns An object containing buy and sell objects.
+ */
+// eslint-disable-next-line max-params, complexity -- Once bound to Client, getOrderbook only has 3 parameters.
+async function getOrderbook(
+  this: Client,
+  currency1: BookOfferCurrency,
+  currency2: BookOfferCurrency,
+  options: {
+    limit?: number
+    ledger_index?: LedgerIndex
+    ledger_hash?: string | null
+    taker?: string | null
+  } = {},
+): Promise<{
+  buy: BookOffer[]
+  sell: BookOffer[]
+}> {
+  Object.keys(options).forEach((key) => {
+    if (!getOrderbookOptionsSet.has(key)) {
+      throw new ValidationError(`Unexpected option: ${key}`, options)
+    }
+  })
+
+  if (options.limit && typeof options.limit !== 'number') {
+    throw new ValidationError('limit must be a number', options.limit)
+  }
+
+  if (
+    options.ledger_index &&
+    !(
+      typeof options.ledger_index === 'number' ||
+      (typeof options.ledger_index === 'string' &&
+        ['validated', 'closed', 'current'].includes(options.ledger_index))
+    )
+  ) {
+    throw new ValidationError(
+      'ledger_index must be a number or a string of "validated", "closed", or "current"',
+      options.ledger_index,
+    )
+  }
+
+  if (
+    options.ledger_hash !== undefined &&
+    options.ledger_hash !== null &&
+    typeof options.ledger_hash !== 'string'
+  ) {
+    throw new ValidationError(
+      'ledger_hash must be a string',
+      options.ledger_hash,
+    )
+  }
+
+  if (options.taker !== undefined && typeof options.taker !== 'string') {
+    throw new ValidationError('taker must be a string', options.taker)
+  }
+
+  const request: BookOffersRequest = {
+    command: 'book_offers',
+    taker_pays: currency1,
+    taker_gets: currency2,
+    ledger_index: options.ledger_index ?? 'validated',
+    ledger_hash: options.ledger_hash === null ? undefined : options.ledger_hash,
+    limit: options.limit ?? DEFAULT_LIMIT,
+    taker: options.taker ? options.taker : undefined,
+  }
+  // 2. Make Request
+  const directOfferResults = await this.requestAll(request)
+  request.taker_gets = currency1
+  request.taker_pays = currency2
+  const reverseOfferResults = await this.requestAll(request)
+  // 3. Return Formatted Response
+  const directOffers = flatMap(
+    directOfferResults,
+    (directOfferResult) => directOfferResult.result.offers,
+  )
+  const reverseOffers = flatMap(
+    reverseOfferResults,
+    (reverseOfferResult) => reverseOfferResult.result.offers,
+  )
+
+  const orders = [...directOffers, ...reverseOffers]
+  // separate out the buy and sell orders
+  const buy: BookOffer[] = []
+  const sell: BookOffer[] = []
+  orders.forEach((order) => {
+    // eslint-disable-next-line no-bitwise -- necessary for flags check
+    if ((order.Flags & OfferFlags.lsfSell) === 0) {
+      buy.push(order)
+    } else {
+      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
+   */
+  return {
+    buy: sortOffers(buy).slice(0, options.limit),
+    sell: sortOffers(sell).slice(0, options.limit),
+  }
+}
+
+export default getOrderbook

package/src/sugar/index.ts

@@ -0,0 +1,11 @@
+export { default as autofill } from './autofill'
+
+export { getBalances, getXrpBalance } from './balances'
+
+export { default as getLedgerIndex } from './getLedgerIndex'
+
+export { default as getOrderbook } from './getOrderbook'
+
+export * from './submit'
+
+export * from './utils'

package/src/sugar/submit.ts

@@ -0,0 +1,305 @@
+import { decode, encode } from 'ripple-binary-codec'
+
+import type { Client, SubmitRequest, SubmitResponse, Wallet } from '..'
+import { ValidationError, XrplError } from '../errors'
+import { Signer } from '../models/common'
+import { TxRequest, TxResponse } from '../models/methods'
+import { Transaction } from '../models/transactions'
+import { BaseTransaction } from '../models/transactions/common'
+import { hashes } from '../utils'
+
+/** Approximate time for a ledger to close, in milliseconds */
+const LEDGER_CLOSE_TIME = 1000
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+/**
+ * Submits a signed/unsigned transaction.
+ * Steps performed on a transaction:
+ *    1. Autofill.
+ *    2. Sign & Encode.
+ *    3. Submit.
+ *
+ * @param this - A Client.
+ * @param transaction - A transaction to autofill, sign & encode, and submit.
+ * @param opts - (Optional) Options used to sign and submit a transaction.
+ * @param opts.autofill - If true, autofill a transaction.
+ * @param opts.failHard - If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
+ * @param opts.wallet - A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
+ * @returns A promise that contains SubmitResponse.
+ * @throws RippledError if submit request fails.
+ */
+async function submit(
+  this: Client,
+  transaction: Transaction | string,
+  opts?: {
+    // If true, autofill a transaction.
+    autofill?: boolean
+    // If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
+    failHard?: boolean
+    // A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
+    wallet?: Wallet
+  },
+): Promise<SubmitResponse> {
+  const signedTx = await getSignedTx(this, transaction, opts)
+  return submitRequest(this, signedTx, opts?.failHard)
+}
+
+/**
+ * Asynchronously submits a transaction and verifies that it has been included in a
+ * validated ledger (or has errored/will not be included for some reason).
+ * See [Reliable Transaction Submission](https://xrpl.org/reliable-transaction-submission.html).
+ *
+ * @example
+ *
+ * ```ts
+ * const { Client, Wallet } = require('xrpl')
+ * const client = new Client('wss://s.altnet.rippletest.net:51233')
+ *
+ * async function submitTransaction() {
+ *   const senderWallet = client.fundWallet()
+ *   const recipientWallet = client.fundWallet()
+ *
+ *   const transaction = {
+ *     TransactionType: 'Payment',
+ *     Account: senderWallet.address,
+ *     Destination: recipientWallet.address,
+ *     Amount: '10'
+ *   }
+ *
+ *   try {
+ *     await client.submit(signedTransaction, { wallet: senderWallet })
+ *     console.log(result)
+ *   } catch (error) {
+ *     console.error(`Failed to submit transaction: ${error}`)
+ *   }
+ * }
+ *
+ * submitTransaction()
+ * ```
+ *
+ * In this example we submit a payment transaction between two newly created testnet accounts.
+ *
+ * Under the hood, `submit` will call `client.autofill` by default, and because we've passed in a `Wallet` it
+ * Will also sign the transaction for us before submitting the signed transaction binary blob to the ledger.
+ *
+ * This is similar to `submitAndWait` which does all of the above, but also waits to see if the transaction has been validated.
+ * @param this - A Client.
+ * @param transaction - A transaction to autofill, sign & encode, and submit.
+ * @param opts - (Optional) Options used to sign and submit a transaction.
+ * @param opts.autofill - If true, autofill a transaction.
+ * @param opts.failHard - If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
+ * @param opts.wallet - A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
+ * @throws Connection errors: If the `Client` object is unable to establish a connection to the specified WebSocket endpoint,
+ * an error will be thrown.
+ * @throws Transaction errors: If the submitted transaction is invalid or cannot be included in a validated ledger for any
+ * reason, the promise returned by `submitAndWait()` will be rejected with an error. This could include issues with insufficient
+ * balance, invalid transaction fields, or other issues specific to the transaction being submitted.
+ * @throws Ledger errors: If the ledger being used to submit the transaction is undergoing maintenance or otherwise unavailable,
+ * an error will be thrown.
+ * @throws Timeout errors: If the transaction takes longer than the specified timeout period to be included in a validated
+ * ledger, the promise returned by `submitAndWait()` will be rejected with an error.
+ * @returns A promise that contains TxResponse, that will return when the transaction has been validated.
+ */
+async function submitAndWait<T extends Transaction = Transaction>(
+  this: Client,
+  transaction: T | string,
+  opts?: {
+    // If true, autofill a transaction.
+    autofill?: boolean
+    // If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
+    failHard?: boolean
+    // A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
+    wallet?: Wallet
+  },
+): Promise<TxResponse<T>> {
+  const signedTx = await getSignedTx(this, transaction, opts)
+
+  const lastLedger = getLastLedgerSequence(signedTx)
+  if (lastLedger == null) {
+    throw new ValidationError(
+      'Transaction must contain a LastLedgerSequence value for reliable submission.',
+    )
+  }
+
+  const response = await submitRequest(this, signedTx, opts?.failHard)
+
+  const txHash = hashes.hashSignedTx(signedTx)
+  return waitForFinalTransactionOutcome(
+    this,
+    txHash,
+    lastLedger,
+    response.result.engine_result,
+  )
+}
+
+// Helper functions
+
+// Encodes and submits a signed transaction.
+async function submitRequest(
+  client: Client,
+  signedTransaction: Transaction | string,
+  failHard = false,
+): Promise<SubmitResponse> {
+  if (!isSigned(signedTransaction)) {
+    throw new ValidationError('Transaction must be signed')
+  }
+
+  const signedTxEncoded =
+    typeof signedTransaction === 'string'
+      ? signedTransaction
+      : encode(signedTransaction)
+  const request: SubmitRequest = {
+    command: 'submit',
+    tx_blob: signedTxEncoded,
+    fail_hard: isAccountDelete(signedTransaction) || failHard,
+  }
+  return client.request(request)
+}
+
+/*
+ * 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).
+ */
+// eslint-disable-next-line max-params, max-lines-per-function -- this function needs to display and do with more information.
+async function waitForFinalTransactionOutcome<
+  T extends BaseTransaction = Transaction,
+>(
+  client: Client,
+  txHash: string,
+  lastLedger: number,
+  submissionResult: string,
+): Promise<TxResponse<T>> {
+  await sleep(LEDGER_CLOSE_TIME)
+
+  const latestLedger = await client.getLedgerIndex()
+
+  if (lastLedger < latestLedger) {
+    throw new XrplError(
+      `The latest ledger sequence ${latestLedger} is greater than the transaction's LastLedgerSequence (${lastLedger}).\n` +
+        `Preliminary result: ${submissionResult}`,
+    )
+  }
+
+  const txResponse = await client
+    .request<TxRequest, TxResponse<T>>({
+      command: 'tx',
+      transaction: txHash,
+    })
+    .catch(async (error) => {
+      // error is of an unknown type and hence we assert type to extract the value we need.
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions,@typescript-eslint/no-unsafe-member-access -- ^
+      const message = error?.data?.error as string
+      if (message === 'txnNotFound') {
+        return waitForFinalTransactionOutcome<T>(
+          client,
+          txHash,
+          lastLedger,
+          submissionResult,
+        )
+      }
+      throw new Error(
+        `${message} \n Preliminary result: ${submissionResult}.\nFull error details: ${String(
+          error,
+        )}`,
+      )
+    })
+
+  if (txResponse.result.validated) {
+    return txResponse
+  }
+
+  return waitForFinalTransactionOutcome<T>(
+    client,
+    txHash,
+    lastLedger,
+    submissionResult,
+  )
+}
+
+// checks if the transaction has been signed
+function isSigned(transaction: Transaction | string): boolean {
+  const tx = typeof transaction === 'string' ? decode(transaction) : transaction
+  if (typeof tx === 'string') {
+    return false
+  }
+  if (tx.Signers != null) {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- we know that tx.Signers is an array of Signers
+    const signers = tx.Signers as Signer[]
+    for (const signer of signers) {
+      // eslint-disable-next-line max-depth -- necessary for checking if signer is signed
+      if (
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- necessary check
+        signer.Signer.SigningPubKey == null ||
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- necessary check
+        signer.Signer.TxnSignature == null
+      ) {
+        return false
+      }
+    }
+    return true
+  }
+  return tx.SigningPubKey != null && tx.TxnSignature != null
+}
+
+// initializes a transaction for a submit request
+async function getSignedTx(
+  client: Client,
+  transaction: Transaction | string,
+  {
+    autofill = true,
+    wallet,
+  }: {
+    // If true, autofill a transaction.
+    autofill?: boolean
+    // If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
+    failHard?: boolean
+    // A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
+    wallet?: Wallet
+  } = {},
+): Promise<Transaction | string> {
+  if (isSigned(transaction)) {
+    return transaction
+  }
+
+  if (!wallet) {
+    throw new ValidationError(
+      'Wallet must be provided when submitting an unsigned transaction',
+    )
+  }
+
+  let tx =
+    typeof transaction === 'string'
+      ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- converts JsonObject to correct Transaction type
+        (decode(transaction) as unknown as Transaction)
+      : transaction
+
+  if (autofill) {
+    tx = await client.autofill(tx)
+  }
+
+  return wallet.sign(tx).tx_blob
+}
+
+// checks if there is a LastLedgerSequence as a part of the transaction
+function getLastLedgerSequence(
+  transaction: Transaction | string,
+): number | null {
+  const tx = typeof transaction === 'string' ? decode(transaction) : transaction
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- converts LastLedgSeq to number if present.
+  return tx.LastLedgerSequence as number | null
+}
+
+// checks if the transaction is an AccountDelete transaction
+function isAccountDelete(transaction: Transaction | string): boolean {
+  const tx = typeof transaction === 'string' ? decode(transaction) : transaction
+  return tx.TransactionType === 'AccountDelete'
+}
+
+export { submit, submitAndWait }

package/src/sugar/utils.ts

@@ -0,0 +1,29 @@
+import { xAddressToClassicAddress, isValidXAddress } from 'ripple-address-codec'
+
+/**
+ * If an address is an X-Address, converts it to a classic address.
+ *
+ * @param account - A classic address or X-address.
+ * @returns The account's classic address.
+ * @throws Error if the X-Address has an associated tag.
+ */
+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`.
+     */
+    if (tag !== false) {
+      throw new Error(
+        'This command does not support the use of a tag. Use an address without a tag.',
+      )
+    }
+
+    // For rippled requests that use an account, always use a classic address.
+    return classicAddress
+  }
+  return account
+}