xrpl 1.0.0-mpt-beta

package/src/sugar/autofill.ts

@@ -0,0 +1,367 @@
+import BigNumber from 'bignumber.js'
+import { xAddressToClassicAddress, isValidXAddress } from 'ripple-address-codec'
+
+import type { Client } from '..'
+import { ValidationError, XrplError } from '../errors'
+import { AccountInfoRequest, AccountObjectsRequest } from '../models/methods'
+import { Transaction } from '../models/transactions'
+import { xrpToDrops } from '../utils'
+
+import getFeeXrp from './getFeeXrp'
+
+// Expire unconfirmed transactions after 20 ledger versions, approximately 1 minute, by default
+const LEDGER_OFFSET = 20
+// Sidechains are expected to have network IDs above this.
+// Networks with ID above this restricted number are expected specify an accurate NetworkID field
+// in every transaction to that chain to prevent replay attacks.
+// Mainnet and testnet are exceptions. More context: https://github.com/XRPLF/rippled/pull/4370
+const RESTRICTED_NETWORKS = 1024
+const REQUIRED_NETWORKID_VERSION = '1.11.0'
+const HOOKS_TESTNET_ID = 21338
+
+/**
+ * Determines whether the source rippled version is not later than the target rippled version.
+ * Example usage: isNotLaterRippledVersion('1.10.0', '1.11.0') returns true.
+ *                isNotLaterRippledVersion('1.10.0', '1.10.0-b1') returns false.
+ *
+ * @param source -- The source rippled version.
+ * @param target -- The target rippled version.
+ * @returns True if source is earlier than target, false otherwise.
+ */
+// eslint-disable-next-line max-lines-per-function, max-statements -- Disable for this helper functions.
+function isNotLaterRippledVersion(source: string, target: string): boolean {
+  if (source === target) {
+    return true
+  }
+  const sourceDecomp = source.split('.')
+  const targetDecomp = target.split('.')
+  const sourceMajor = parseInt(sourceDecomp[0], 10)
+  const sourceMinor = parseInt(sourceDecomp[1], 10)
+  const targetMajor = parseInt(targetDecomp[0], 10)
+  const targetMinor = parseInt(targetDecomp[1], 10)
+  // Compare major version
+  if (sourceMajor !== targetMajor) {
+    return sourceMajor < targetMajor
+  }
+  // Compare minor version
+  if (sourceMinor !== targetMinor) {
+    return sourceMinor < targetMinor
+  }
+  const sourcePatch = sourceDecomp[2].split('-')
+  const targetPatch = targetDecomp[2].split('-')
+
+  const sourcePatchVersion = parseInt(sourcePatch[0], 10)
+  const targetPatchVersion = parseInt(targetPatch[0], 10)
+
+  // Compare patch version
+  if (sourcePatchVersion !== targetPatchVersion) {
+    return sourcePatchVersion < targetPatchVersion
+  }
+
+  // Compare release version
+  if (sourcePatch.length !== targetPatch.length) {
+    return sourcePatch.length > targetPatch.length
+  }
+
+  if (sourcePatch.length === 2) {
+    // Compare different release types
+    if (!sourcePatch[1][0].startsWith(targetPatch[1][0])) {
+      return sourcePatch[1] < targetPatch[1]
+    }
+    // Compare beta version
+    if (sourcePatch[1].startsWith('b')) {
+      return (
+        parseInt(sourcePatch[1].slice(1), 10) <
+        parseInt(targetPatch[1].slice(1), 10)
+      )
+    }
+    // Compare rc version
+    return (
+      parseInt(sourcePatch[1].slice(2), 10) <
+      parseInt(targetPatch[1].slice(2), 10)
+    )
+  }
+
+  return false
+}
+
+/**
+ * Determine if the transaction required a networkID to be valid.
+ * Transaction needs networkID if later than restricted ID and either the network is hooks testnet
+ * or build version is >= 1.11.0
+ *
+ * @param client -- The connected client.
+ * @returns True if required networkID, false otherwise.
+ */
+export function txNeedsNetworkID(client: Client): boolean {
+  if (
+    client.networkID !== undefined &&
+    client.networkID > RESTRICTED_NETWORKS
+  ) {
+    if (
+      (client.buildVersion &&
+        isNotLaterRippledVersion(
+          REQUIRED_NETWORKID_VERSION,
+          client.buildVersion,
+        )) ||
+      client.networkID === HOOKS_TESTNET_ID
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+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) {
+    validateAccountAddress(tx, 'Destination', 'DestinationTag')
+  }
+
+  // DepositPreauth:
+  convertToClassicAddress(tx, 'Authorize')
+  convertToClassicAddress(tx, 'Unauthorize')
+  // EscrowCancel, EscrowFinish:
+  convertToClassicAddress(tx, 'Owner')
+  // SetRegularKey:
+  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,
+  tagField: string,
+): void {
+  // if X-address is given, convert it to classic address
+  const { classicAccount, tag } = getClassicAccountAndTag(tx[accountField])
+  // eslint-disable-next-line no-param-reassign -- param reassign is safe
+  tx[accountField] = classicAccount
+
+  if (tag != null && tag !== false) {
+    if (tx[tagField] && tx[tagField] !== tag) {
+      throw new ValidationError(
+        `The ${tagField}, if present, must match the tag of the ${accountField} X-address`,
+      )
+    }
+    // eslint-disable-next-line no-param-reassign -- param reassign is safe
+    tx[tagField] = tag
+  }
+}
+
+/**
+ * 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,
+): ClassicAccountAndTag {
+  if (isValidXAddress(Account)) {
+    const classic = xAddressToClassicAddress(Account)
+    if (expectedTag != null && classic.tag !== expectedTag) {
+      throw new ValidationError(
+        'address includes a tag that does not match the tag specified in the transaction',
+      )
+    }
+    return {
+      classicAccount: classic.classicAddress,
+      tag: classic.tag,
+    }
+  }
+  return {
+    classicAccount: Account,
+    tag: expectedTag,
+  }
+}
+
+/**
+ * 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]
+  if (typeof account === 'string') {
+    const { classicAccount } = getClassicAccountAndTag(account)
+    // eslint-disable-next-line no-param-reassign -- param reassign is safe
+    tx[fieldName] = classicAccount
+  }
+}
+
+/**
+ * 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> {
+  const request: AccountInfoRequest = {
+    command: 'account_info',
+    account: tx.Account,
+    ledger_index: 'current',
+  }
+  const data = await client.request(request)
+  // eslint-disable-next-line no-param-reassign, require-atomic-updates -- param reassign is safe with no race condition
+  tx.Sequence = data.result.account_data.Sequence
+}
+
+/**
+ * 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
+
+  if (fee == null) {
+    return Promise.reject(new Error('Could not fetch Owner Reserve.'))
+  }
+
+  return new BigNumber(fee)
+}
+
+/**
+ * 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,
+): Promise<void> {
+  // netFee is usually 0.00001 XRP (10 drops)
+  const netFeeXRP = await getFeeXrp(client)
+  const netFeeDrops = xrpToDrops(netFeeXRP)
+  let baseFee = new BigNumber(netFeeDrops)
+
+  // EscrowFinish Transaction with Fulfillment
+  if (tx.TransactionType === 'EscrowFinish' && tx.Fulfillment != null) {
+    const fulfillmentBytesSize: number = Math.ceil(tx.Fulfillment.length / 2)
+    // 10 drops × (33 + (Fulfillment size in bytes / 16))
+    const product = new BigNumber(
+      // eslint-disable-next-line @typescript-eslint/no-magic-numbers -- expected use of magic numbers
+      scaleValue(netFeeDrops, 33 + fulfillmentBytesSize / 16),
+    )
+    baseFee = product.dp(0, BigNumber.ROUND_CEIL)
+  }
+
+  if (
+    tx.TransactionType === 'AccountDelete' ||
+    tx.TransactionType === 'AMMCreate'
+  ) {
+    baseFee = await fetchAccountDeleteFee(client)
+  }
+
+  /*
+   * Multi-signed Transaction
+   * 10 drops × (1 + Number of Signatures Provided)
+   */
+  if (signersCount > 0) {
+    baseFee = BigNumber.sum(baseFee, scaleValue(netFeeDrops, 1 + signersCount))
+  }
+
+  const maxFeeDrops = xrpToDrops(client.maxFeeXRP)
+  const totalFee =
+    tx.TransactionType === 'AccountDelete'
+      ? baseFee
+      : BigNumber.min(baseFee, maxFeeDrops)
+
+  // Round up baseFee and return it as a string
+  // eslint-disable-next-line no-param-reassign, @typescript-eslint/no-magic-numbers -- param reassign is safe, base 10 magic num
+  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()
+}
+
+/**
+ * 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> {
+  const ledgerSequence = await client.getLedgerIndex()
+  // eslint-disable-next-line no-param-reassign -- param reassign is safe
+  tx.LastLedgerSequence = ledgerSequence + LEDGER_OFFSET
+}
+
+/**
+ * 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> {
+  const request: AccountObjectsRequest = {
+    command: 'account_objects',
+    account: tx.Account,
+    ledger_index: 'validated',
+    deletion_blockers_only: true,
+  }
+  const response = await client.request(request)
+  return new Promise((resolve, reject) => {
+    if (response.result.account_objects.length > 0) {
+      reject(
+        new XrplError(
+          `Account ${tx.Account} cannot be deleted; there are Escrows, PayChannels, RippleStates, or Checks associated with the account.`,
+          response.result.account_objects,
+        ),
+      )
+    }
+    resolve()
+  })
+}

package/src/sugar/balances.ts

@@ -0,0 +1,15 @@
+import { AccountLinesTrustline, Balance } from '../models'
+
+/**
+ * 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,
+  }))
+}

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/getOrderbook.ts

@@ -0,0 +1,229 @@
+import BigNumber from 'bignumber.js'
+
+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',
+])
+
+/**
+ * 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 options - The options to validate.
+ * @throws {ValidationError} If any validation errors occur.
+ */
+// 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)
+  }
+
+  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)
+  }
+}
+
+/**
+ * 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,
+    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,
+  }
+
+  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) {
+      buy.push(order)
+    } else {
+      sell.push(order)
+    }
+  })
+
+  return { buy, sell }
+}
+
+/**
+ * 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

@@ -0,0 +1,3 @@
+export * from './submit'
+
+export * from './utils'