xrpl 2.13.0 → 3.0.0-beta.0

package/src/models/transactions/transaction.ts

@@ -18,7 +18,7 @@ import { CheckCancel, validateCheckCancel } from './checkCancel'
 import { CheckCash, validateCheckCash } from './checkCash'
 import { CheckCreate, validateCheckCreate } from './checkCreate'
 import { Clawback, validateClawback } from './clawback'
-import { isIssuedCurrency } from './common'
+import { BaseTransaction, isIssuedCurrency } from './common'
 import { DepositPreauth, validateDepositPreauth } from './depositPreauth'
 import { EnableAmendment } from './enableAmendment'
 import { EscrowCancel, validateEscrowCancel } from './escrowCancel'
@@ -136,9 +136,11 @@ export type PseudoTransaction = EnableAmendment | SetFee | UNLModify
 /**
  * @category Transaction Models
  */
-export interface TransactionAndMetadata {
-  transaction: Transaction
-  metadata: TransactionMetadata
+export interface TransactionAndMetadata<
+  T extends BaseTransaction = Transaction,
+> {
+  transaction: T
+  metadata: TransactionMetadata<T>
 }
 
 /**

package/src/sugar/autofill.ts

@@ -5,7 +5,6 @@ import type { Client } from '..'
 import { ValidationError, XrplError } from '../errors'
 import { AccountInfoRequest, AccountObjectsRequest } from '../models/methods'
 import { Transaction } from '../models/transactions'
-import { setTransactionFlagsToNumber } from '../models/utils/flags'
 import { xrpToDrops } from '../utils'
 
 import getFeeXrp from './getFeeXrp'
@@ -19,83 +18,6 @@ const LEDGER_OFFSET = 20
 const RESTRICTED_NETWORKS = 1024
 const REQUIRED_NETWORKID_VERSION = '1.11.0'
 const HOOKS_TESTNET_ID = 21338
-interface ClassicAccountAndTag {
-  classicAccount: string
-  tag: number | false | undefined
-}
-
-/**
- * Autofills fields in a transaction. This will set `Sequence`, `Fee`,
- * `lastLedgerSequence` according to the current state of the server this Client
- * is connected to. It also converts all X-Addresses to classic addresses and
- * flags interfaces into numbers.
- *
- * @example
- *
- * ```ts
- * const { Client } = require('xrpl')
- *
- * const client = new Client('wss://s.altnet.rippletest.net:51233')
- *
- * async function createAndAutofillTransaction() {
- *   const transaction = {
- *     TransactionType: 'Payment',
- *     Account: 'rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh',
- *     Destination: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
- *     Amount: '10000000' // 10 XRP in drops (1/1,000,000th of an XRP)
- *   }
- *
- *   try {
- *     const autofilledTransaction = await client.autofill(transaction)
- *     console.log(autofilledTransaction)
- *   } catch (error) {
- *     console.error(`Failed to autofill transaction: ${error}`)
- *   }
- * }
- *
- * createAndAutofillTransaction()
- * ```
- *
- * Autofill helps fill in fields which should be included in a transaction, but can be determined automatically
- * such as `LastLedgerSequence` and `Fee`. If you override one of the fields `autofill` changes, your explicit
- * values will be used instead. By default, this is done as part of `submit` and `submitAndWait` when you pass
- * in an unsigned transaction along with your wallet to be submitted.
- *
- * @param this - A client.
- * @param transaction - A {@link Transaction} in JSON format
- * @param signersCount - The expected number of signers for this transaction.
- * Only used for multisigned transactions.
- * @returns The autofilled transaction.
- */
-async function autofill<T extends Transaction>(
-  this: Client,
-  transaction: T,
-  signersCount?: number,
-): Promise<T> {
-  const tx = { ...transaction }
-
-  setValidAddresses(tx)
-
-  setTransactionFlagsToNumber(tx)
-  const promises: Array<Promise<void>> = []
-  if (tx.NetworkID == null) {
-    tx.NetworkID = txNeedsNetworkID(this) ? this.networkID : undefined
-  }
-  if (tx.Sequence == null) {
-    promises.push(setNextValidSequenceNumber(this, tx))
-  }
-  if (tx.Fee == null) {
-    promises.push(calculateFeePerTransactionType(this, tx, signersCount))
-  }
-  if (tx.LastLedgerSequence == null) {
-    promises.push(setLatestValidatedLedgerSequence(this, tx))
-  }
-  if (tx.TransactionType === 'AccountDelete') {
-    promises.push(checkAccountDeleteBlockers(this, tx))
-  }
-
-  return Promise.all(promises).then(() => tx)
-}
 
 /**
  * Determines whether the source rippled version is not later than the target rippled version.
@@ -171,7 +93,7 @@ function isNotLaterRippledVersion(source: string, target: string): boolean {
  * @param client -- The connected client.
  * @returns True if required networkID, false otherwise.
  */
-function txNeedsNetworkID(client: Client): boolean {
+export function txNeedsNetworkID(client: Client): boolean {
   if (
     client.networkID !== undefined &&
     client.networkID > RESTRICTED_NETWORKS
@@ -190,7 +112,17 @@ function txNeedsNetworkID(client: Client): boolean {
   return false
 }
 
-function setValidAddresses(tx: Transaction): void {
+interface ClassicAccountAndTag {
+  classicAccount: string
+  tag: number | false | undefined
+}
+
+/**
+ * Sets valid addresses for the transaction.
+ *
+ * @param tx - The transaction object.
+ */
+export function setValidAddresses(tx: Transaction): void {
   validateAccountAddress(tx, 'Account', 'SourceTag')
   // eslint-disable-next-line @typescript-eslint/dot-notation -- Destination can exist on Transaction
   if (tx['Destination'] != null) {
@@ -206,6 +138,14 @@ function setValidAddresses(tx: Transaction): void {
   convertToClassicAddress(tx, 'RegularKey')
 }
 
+/**
+ * Validates the account address in a transaction object.
+ *
+ * @param tx - The transaction object.
+ * @param accountField - The field name for the account address in the transaction object.
+ * @param tagField - The field name for the tag in the transaction object.
+ * @throws {ValidationError} If the tag field does not match the tag of the account address.
+ */
 function validateAccountAddress(
   tx: Transaction,
   accountField: string,
@@ -227,6 +167,14 @@ function validateAccountAddress(
   }
 }
 
+/**
+ * Retrieves the classic account and tag from an account address.
+ *
+ * @param Account - The account address.
+ * @param [expectedTag] - The expected tag for the account address.
+ * @returns The classic account and tag.
+ * @throws {ValidationError} If the address includes a tag that does not match the tag specified in the transaction.
+ */
 function getClassicAccountAndTag(
   Account: string,
   expectedTag?: number,
@@ -249,6 +197,12 @@ function getClassicAccountAndTag(
   }
 }
 
+/**
+ * Converts the specified field of a transaction object to a classic address format.
+ *
+ * @param tx - The transaction object.
+ * @param fieldName - The name of the field to convert.export
+ */
 function convertToClassicAddress(tx: Transaction, fieldName: string): void {
   // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- assignment is safe
   const account = tx[fieldName]
@@ -259,7 +213,15 @@ function convertToClassicAddress(tx: Transaction, fieldName: string): void {
   }
 }
 
-async function setNextValidSequenceNumber(
+/**
+ * Sets the next valid sequence number for a transaction.
+ *
+ * @param client - The client object used for making requests.
+ * @param tx - The transaction object for which the sequence number needs to be set.
+ * @returns A Promise that resolves when the sequence number is set.
+ * @throws {Error} If there is an error retrieving the account information.
+ */
+export async function setNextValidSequenceNumber(
   client: Client,
   tx: Transaction,
 ): Promise<void> {
@@ -273,7 +235,14 @@ async function setNextValidSequenceNumber(
   tx.Sequence = data.result.account_data.Sequence
 }
 
-async function fetchOwnerReserveFee(client: Client): Promise<BigNumber> {
+/**
+ * Fetches the account deletion fee from the server state using the provided client.
+ *
+ * @param client - The client object used to make the request.
+ * @returns A Promise that resolves to the account deletion fee as a BigNumber.
+ * @throws {Error} Throws an error if the account deletion fee cannot be fetched.
+ */
+async function fetchAccountDeleteFee(client: Client): Promise<BigNumber> {
   const response = await client.request({ command: 'server_state' })
   const fee = response.result.state.validated_ledger?.reserve_inc
 
@@ -284,7 +253,15 @@ async function fetchOwnerReserveFee(client: Client): Promise<BigNumber> {
   return new BigNumber(fee)
 }
 
-async function calculateFeePerTransactionType(
+/**
+ * Calculates the fee per transaction type.
+ *
+ * @param client - The client object.
+ * @param tx - The transaction object.
+ * @param [signersCount=0] - The number of signers (default is 0). Only used for multisigning.
+ * @returns A promise that resolves with void. Modifies the `tx` parameter to give it the calculated fee.
+ */
+export async function calculateFeePerTransactionType(
   client: Client,
   tx: Transaction,
   signersCount = 0,
@@ -309,7 +286,7 @@ async function calculateFeePerTransactionType(
     tx.TransactionType === 'AccountDelete' ||
     tx.TransactionType === 'AMMCreate'
   ) {
-    baseFee = await fetchOwnerReserveFee(client)
+    baseFee = await fetchAccountDeleteFee(client)
   }
 
   /*
@@ -331,11 +308,25 @@ async function calculateFeePerTransactionType(
   tx.Fee = totalFee.dp(0, BigNumber.ROUND_CEIL).toString(10)
 }
 
+/**
+ * Scales the given value by multiplying it with the provided multiplier.
+ *
+ * @param value - The value to be scaled.
+ * @param multiplier - The multiplier to scale the value.
+ * @returns The scaled value as a string.
+ */
 function scaleValue(value, multiplier): string {
   return new BigNumber(value).times(multiplier).toString()
 }
 
-async function setLatestValidatedLedgerSequence(
+/**
+ * Sets the latest validated ledger sequence for the transaction.
+ *
+ * @param client - The client object.
+ * @param tx - The transaction object.
+ * @returns A promise that resolves with void. Modifies the `tx` parameter setting `LastLedgerSequence`.
+ */
+export async function setLatestValidatedLedgerSequence(
   client: Client,
   tx: Transaction,
 ): Promise<void> {
@@ -344,7 +335,14 @@ async function setLatestValidatedLedgerSequence(
   tx.LastLedgerSequence = ledgerSequence + LEDGER_OFFSET
 }
 
-async function checkAccountDeleteBlockers(
+/**
+ * Checks for any blockers that prevent the deletion of an account.
+ *
+ * @param client - The client object.
+ * @param tx - The transaction object.
+ * @returns A promise that resolves with void if there are no blockers, or rejects with an XrplError if there are blockers.
+ */
+export async function checkAccountDeleteBlockers(
   client: Client,
   tx: Transaction,
 ): Promise<void> {
@@ -367,5 +365,3 @@ async function checkAccountDeleteBlockers(
     resolve()
   })
 }
-
-export default autofill

package/src/sugar/balances.ts

@@ -1,123 +1,15 @@
-import flatMap from 'lodash/flatMap'
+import { AccountLinesTrustline, Balance } from '../models'
 
-import type { Balance, Client } from '..'
-import {
-  AccountLinesRequest,
-  AccountLinesTrustline,
-  LedgerIndex,
-  AccountInfoRequest,
-} from '../models'
-import { dropsToXrp } from '../utils'
-
-function formatBalances(trustlines: AccountLinesTrustline[]): Balance[] {
+/**
+ * Formats an array of trustlines into an array of balances.
+ *
+ * @param trustlines - The array of trustlines to format.
+ * @returns An array of balances, each containing the value, currency, and issuer.
+ */
+export 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/getOrderbook.ts

@@ -1,6 +1,4 @@
-/* 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'
@@ -31,43 +29,40 @@ const getOrderbookOptionsSet = new Set([
 ])
 
 /**
- * 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.
+ * Represents the options for retrieving the order book.
+ */
+export interface GetOrderBookOptions {
+  /**
+   * The limit on the number of offers to return.
+   */
+  limit?: number
+  /**
+   * The ledger index of the ledger to use.
+   */
+  ledger_index?: LedgerIndex
+  /**
+   * The ledger hash of the ledger to use.
+   */
+  ledger_hash?: string | null
+  /**
+   * The account that takes the offers.
+   */
+  taker?: string | null
+}
+
+/**
+ * Validates the options for retrieving the order book.
  *
- * @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.
+ * @param options - The options to validate.
+ * @throws {ValidationError} If any validation errors occur.
  */
-// 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) => {
+// eslint-disable-next-line complexity -- Necessary for validation.
+export function validateOrderbookOptions(options: GetOrderBookOptions): void {
+  for (const key of Object.keys(options)) {
     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)
@@ -101,7 +96,30 @@ async function getOrderbook(
   if (options.taker !== undefined && typeof options.taker !== 'string') {
     throw new ValidationError('taker must be a string', options.taker)
   }
+}
 
+/**
+ * Creates a request object for retrieving book offers.
+ *
+ * @param currency1 - The first currency in the pair.
+ * @param currency2 - The second currency in the pair.
+ * @param options - Additional options for the request.
+ * @param [options.limit] - The maximum number of offers to retrieve.
+ * @param [options.ledger_index] - The ledger index to use for retrieval.
+ * @param [options.ledger_hash] - The ledger hash to use for retrieval.
+ * @param [options.taker] - The taker address for retrieval.
+ * @returns The created request object.
+ */
+export function createBookOffersRequest(
+  currency1: BookOfferCurrency,
+  currency2: BookOfferCurrency,
+  options: {
+    limit?: number
+    ledger_index?: LedgerIndex
+    ledger_hash?: string | null
+    taker?: string | null
+  },
+): BookOffersRequest {
   const request: BookOffersRequest = {
     command: 'book_offers',
     taker_pays: currency1,
@@ -111,25 +129,78 @@ async function getOrderbook(
     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
+
+  return request
+}
+
+type BookOfferResult = BookOffer[]
+
+/**
+ * Retrieves all book offer results using the given request.
+ *
+ * @param client - The Ripple client.
+ * @param request - The request object.
+ * @returns The array of book offer results.
+ */
+export async function requestAllOffers(
+  client: Client,
+  request: BookOffersRequest,
+): Promise<BookOfferResult[]> {
+  const results = await client.requestAll(request)
+  return results.map((result) => result.result.offers)
+}
+
+/**
+ * Creates a reverse request object by swapping the taker pays and taker gets amounts.
+ *
+ * @param request - The original request object.
+ * @returns The reverse request object.
+ */
+export function reverseRequest(request: BookOffersRequest): BookOffersRequest {
+  return {
+    ...request,
+    taker_pays: request.taker_gets,
+    taker_gets: request.taker_pays,
+  }
+}
+
+/**
+ * Extracts the offers from the book offer results.
+ *
+ * @param offerResults - The array of book offer results.
+ * @returns The extracted offers.
+ */
+export function extractOffers(offerResults: BookOfferResult[]): BookOffer[] {
+  return offerResults.flatMap((offerResult) => offerResult)
+}
+
+/**
+ * Combines the direct and reverse offers into a single array.
+ *
+ * @param directOffers - The direct offers.
+ * @param reverseOffers - The reverse offers.
+ * @returns The combined array of offers.
+ */
+export function combineOrders(
+  directOffers: BookOffer[],
+  reverseOffers: BookOffer[],
+): BookOffer[] {
+  return [...directOffers, ...reverseOffers]
+}
+
+/**
+ * Separates the buy and sell orders from the given array of orders.
+ *
+ * @param orders - The array of orders.
+ * @returns The separated buy and sell orders.
+ */
+export function separateBuySellOrders(orders: BookOffer[]): {
+  buy: BookOffer[]
+  sell: BookOffer[]
+} {
   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) {
@@ -138,15 +209,21 @@ 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
-   */
-  return {
-    buy: sortOffers(buy).slice(0, options.limit),
-    sell: sortOffers(sell).slice(0, options.limit),
-  }
+
+  return { buy, sell }
 }
 
-export default getOrderbook
+/**
+ * Sorts and limits the given array of offers.
+ *
+ * @param offers - The array of offers to sort and limit.
+ * @param [limit] - The maximum number of offers to include.
+ * @returns The sorted and limited array of offers.
+ */
+export function sortAndLimitOffers(
+  offers: BookOffer[],
+  limit?: number,
+): BookOffer[] {
+  const sortedOffers = sortOffers(offers)
+  return sortedOffers.slice(0, limit)
+}

package/src/sugar/index.ts

@@ -1,11 +1,3 @@
-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'