xrpl 2.10.0 → 2.12.0-beta.0

package/src/models/transactions/transaction.ts

@@ -0,0 +1,370 @@
+/* eslint-disable max-lines -- need to work with a lot of transactions in a switch statement */
+/* eslint-disable complexity -- verifies many tx types hence a lot of checks needed */
+/* eslint-disable max-lines-per-function -- need to work with a lot of Tx verifications */
+
+import { ValidationError } from '../../errors'
+import { IssuedCurrencyAmount, Memo } from '../common'
+import { isHex } from '../utils'
+import { setTransactionFlagsToNumber } from '../utils/flags'
+
+import { AccountDelete, validateAccountDelete } from './accountDelete'
+import { AccountSet, validateAccountSet } from './accountSet'
+import { AMMBid, validateAMMBid } from './AMMBid'
+import { AMMCreate, validateAMMCreate } from './AMMCreate'
+import { AMMDelete, validateAMMDelete } from './AMMDelete'
+import { AMMDeposit, validateAMMDeposit } from './AMMDeposit'
+import { AMMVote, validateAMMVote } from './AMMVote'
+import { AMMWithdraw, validateAMMWithdraw } from './AMMWithdraw'
+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 { DepositPreauth, validateDepositPreauth } from './depositPreauth'
+import { EscrowCancel, validateEscrowCancel } from './escrowCancel'
+import { EscrowCreate, validateEscrowCreate } from './escrowCreate'
+import { EscrowFinish, validateEscrowFinish } from './escrowFinish'
+import { TransactionMetadata } from './metadata'
+import {
+  NFTokenAcceptOffer,
+  validateNFTokenAcceptOffer,
+} from './NFTokenAcceptOffer'
+import { NFTokenBurn, validateNFTokenBurn } from './NFTokenBurn'
+import {
+  NFTokenCancelOffer,
+  validateNFTokenCancelOffer,
+} from './NFTokenCancelOffer'
+import {
+  NFTokenCreateOffer,
+  validateNFTokenCreateOffer,
+} from './NFTokenCreateOffer'
+import { NFTokenMint, validateNFTokenMint } from './NFTokenMint'
+import { OfferCancel, validateOfferCancel } from './offerCancel'
+import { OfferCreate, validateOfferCreate } from './offerCreate'
+import { Payment, validatePayment } from './payment'
+import {
+  PaymentChannelClaim,
+  validatePaymentChannelClaim,
+} from './paymentChannelClaim'
+import {
+  PaymentChannelCreate,
+  validatePaymentChannelCreate,
+} from './paymentChannelCreate'
+import {
+  PaymentChannelFund,
+  validatePaymentChannelFund,
+} from './paymentChannelFund'
+import { SetRegularKey, validateSetRegularKey } from './setRegularKey'
+import { SignerListSet, validateSignerListSet } from './signerListSet'
+import { TicketCreate, validateTicketCreate } from './ticketCreate'
+import { TrustSet, validateTrustSet } from './trustSet'
+import {
+  XChainAccountCreateCommit,
+  validateXChainAccountCreateCommit,
+} from './XChainAccountCreateCommit'
+import {
+  XChainAddAccountCreateAttestation,
+  validateXChainAddAccountCreateAttestation,
+} from './XChainAddAccountCreateAttestation'
+import {
+  XChainAddClaimAttestation,
+  validateXChainAddClaimAttestation,
+} from './XChainAddClaimAttestation'
+import { XChainClaim, validateXChainClaim } from './XChainClaim'
+import { XChainCommit, validateXChainCommit } from './XChainCommit'
+import {
+  XChainCreateBridge,
+  validateXChainCreateBridge,
+} from './XChainCreateBridge'
+import {
+  XChainCreateClaimID,
+  validateXChainCreateClaimID,
+} from './XChainCreateClaimID'
+import {
+  XChainModifyBridge,
+  validateXChainModifyBridge,
+} from './XChainModifyBridge'
+
+/**
+ * @category Transaction Models
+ */
+export type Transaction =
+  | AccountDelete
+  | AccountSet
+  | AMMBid
+  | AMMDelete
+  | AMMDeposit
+  | AMMCreate
+  | AMMVote
+  | AMMWithdraw
+  | CheckCancel
+  | CheckCash
+  | CheckCreate
+  | Clawback
+  | DepositPreauth
+  | EscrowCancel
+  | EscrowCreate
+  | EscrowFinish
+  | NFTokenAcceptOffer
+  | NFTokenBurn
+  | NFTokenCancelOffer
+  | NFTokenCreateOffer
+  | NFTokenMint
+  | OfferCancel
+  | OfferCreate
+  | Payment
+  | PaymentChannelClaim
+  | PaymentChannelCreate
+  | PaymentChannelFund
+  | SetRegularKey
+  | SignerListSet
+  | TicketCreate
+  | TrustSet
+  | XChainAddAccountCreateAttestation
+  | XChainAddClaimAttestation
+  | XChainClaim
+  | XChainCommit
+  | XChainCreateBridge
+  | XChainCreateClaimID
+  | XChainAccountCreateCommit
+  | XChainModifyBridge
+
+/**
+ * @category Transaction Models
+ */
+export interface TransactionAndMetadata {
+  transaction: Transaction
+  metadata: TransactionMetadata
+}
+
+/**
+ * Verifies various Transaction Types.
+ * Encode/decode and individual type validation.
+ *
+ * @param transaction - A Transaction.
+ * @throws ValidationError When the Transaction is malformed.
+ * @category Utilities
+ */
+export function validate(transaction: Record<string, unknown>): void {
+  const tx = { ...transaction }
+  if (tx.TransactionType == null) {
+    throw new ValidationError('Object does not have a `TransactionType`')
+  }
+  if (typeof tx.TransactionType !== 'string') {
+    throw new ValidationError("Object's `TransactionType` is not a string")
+  }
+
+  /*
+   * - Memos have exclusively hex data.
+   */
+  if (tx.Memos != null && typeof tx.Memos !== 'object') {
+    throw new ValidationError('Memo must be array')
+  }
+  if (tx.Memos != null) {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- needed here
+    ;(tx.Memos as Array<Memo | null>).forEach((memo) => {
+      if (memo?.Memo == null) {
+        throw new ValidationError('Memo data must be in a `Memo` field')
+      }
+      if (memo.Memo.MemoData) {
+        if (!isHex(memo.Memo.MemoData)) {
+          throw new ValidationError('MemoData field must be a hex value')
+        }
+      }
+
+      if (memo.Memo.MemoType) {
+        if (!isHex(memo.Memo.MemoType)) {
+          throw new ValidationError('MemoType field must be a hex value')
+        }
+      }
+
+      if (memo.Memo.MemoFormat) {
+        if (!isHex(memo.Memo.MemoFormat)) {
+          throw new ValidationError('MemoFormat field must be a hex value')
+        }
+      }
+    })
+  }
+
+  Object.keys(tx).forEach((key) => {
+    const standard_currency_code_len = 3
+    if (tx[key] && isIssuedCurrency(tx[key])) {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- needed
+      const txCurrency = (tx[key] as IssuedCurrencyAmount).currency
+
+      if (
+        txCurrency.length === standard_currency_code_len &&
+        txCurrency.toUpperCase() === 'XRP'
+      ) {
+        throw new ValidationError(
+          `Cannot have an issued currency with a similar standard code to XRP (received '${txCurrency}'). XRP is not an issued currency.`,
+        )
+      }
+    }
+  })
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- okay here
+  setTransactionFlagsToNumber(tx as unknown as Transaction)
+  switch (tx.TransactionType) {
+    case 'AccountDelete':
+      validateAccountDelete(tx)
+      break
+
+    case 'AccountSet':
+      validateAccountSet(tx)
+      break
+
+    case 'AMMBid':
+      validateAMMBid(tx)
+      break
+
+    case 'AMMDelete':
+      validateAMMDelete(tx)
+      break
+
+    case 'AMMDeposit':
+      validateAMMDeposit(tx)
+      break
+
+    case 'AMMCreate':
+      validateAMMCreate(tx)
+      break
+
+    case 'AMMVote':
+      validateAMMVote(tx)
+      break
+
+    case 'AMMWithdraw':
+      validateAMMWithdraw(tx)
+      break
+
+    case 'CheckCancel':
+      validateCheckCancel(tx)
+      break
+
+    case 'CheckCash':
+      validateCheckCash(tx)
+      break
+
+    case 'CheckCreate':
+      validateCheckCreate(tx)
+      break
+
+    case 'Clawback':
+      validateClawback(tx)
+      break
+
+    case 'DepositPreauth':
+      validateDepositPreauth(tx)
+      break
+
+    case 'EscrowCancel':
+      validateEscrowCancel(tx)
+      break
+
+    case 'EscrowCreate':
+      validateEscrowCreate(tx)
+      break
+
+    case 'EscrowFinish':
+      validateEscrowFinish(tx)
+      break
+
+    case 'NFTokenAcceptOffer':
+      validateNFTokenAcceptOffer(tx)
+      break
+
+    case 'NFTokenBurn':
+      validateNFTokenBurn(tx)
+      break
+
+    case 'NFTokenCancelOffer':
+      validateNFTokenCancelOffer(tx)
+      break
+
+    case 'NFTokenCreateOffer':
+      validateNFTokenCreateOffer(tx)
+      break
+
+    case 'NFTokenMint':
+      validateNFTokenMint(tx)
+      break
+
+    case 'OfferCancel':
+      validateOfferCancel(tx)
+      break
+
+    case 'OfferCreate':
+      validateOfferCreate(tx)
+      break
+
+    case 'Payment':
+      validatePayment(tx)
+      break
+
+    case 'PaymentChannelClaim':
+      validatePaymentChannelClaim(tx)
+      break
+
+    case 'PaymentChannelCreate':
+      validatePaymentChannelCreate(tx)
+      break
+
+    case 'PaymentChannelFund':
+      validatePaymentChannelFund(tx)
+      break
+
+    case 'SetRegularKey':
+      validateSetRegularKey(tx)
+      break
+
+    case 'SignerListSet':
+      validateSignerListSet(tx)
+      break
+
+    case 'TicketCreate':
+      validateTicketCreate(tx)
+      break
+
+    case 'TrustSet':
+      validateTrustSet(tx)
+      break
+
+    case 'XChainAddAccountCreateAttestation':
+      validateXChainAddAccountCreateAttestation(tx)
+      break
+
+    case 'XChainAddClaimAttestation':
+      validateXChainAddClaimAttestation(tx)
+      break
+
+    case 'XChainClaim':
+      validateXChainClaim(tx)
+      break
+
+    case 'XChainCommit':
+      validateXChainCommit(tx)
+      break
+
+    case 'XChainCreateBridge':
+      validateXChainCreateBridge(tx)
+      break
+
+    case 'XChainCreateClaimID':
+      validateXChainCreateClaimID(tx)
+      break
+
+    case 'XChainAccountCreateCommit':
+      validateXChainAccountCreateCommit(tx)
+      break
+
+    case 'XChainModifyBridge':
+      validateXChainModifyBridge(tx)
+      break
+
+    default:
+      throw new ValidationError(
+        `Invalid field TransactionType: ${tx.TransactionType}`,
+      )
+  }
+}

package/src/models/transactions/trustSet.ts

@@ -0,0 +1,146 @@
+import { ValidationError } from '../../errors'
+import { IssuedCurrencyAmount } from '../common'
+
+import {
+  BaseTransaction,
+  GlobalFlags,
+  isAmount,
+  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
+ *
+ * @example
+ * ```typescript
+ *
+ * const trustSetTx: TrustSet = {
+ *  TransactionType: 'TrustSet',
+ *  Account: wallet2.getClassicAddress(),
+ *  LimitAmount: {
+ *    currency: 'FOO',
+ *    issuer: wallet1.getClassicAddress(),
+ *    value: '10000000000',
+ *  },
+ *  Flags: {
+ *    tfSetNoRipple: true
+ *  }
+ * }
+ *
+ * // Autofill the tx to see how flags actually look compared to the interface usage.
+ * const autofilledTx = await client.autofill(trustSetTx)
+ * console.log(autofilledTx)
+ * // {
+ * //  TransactionType: 'TrustSet',
+ * //  Account: 'r9dAdQQCBcGajVSeC9CqW3LCugjPDnAkEb',
+ * //  LimitAmount: {
+ * //   currency: 'FOO',
+ * //   issuer: 'rWZzUjo5xGiAoRBqzsndyzonXz47UV8u1',
+ * //   value: '10000000000'
+ * //  },
+ * //  Flags: 131072,
+ * //  Sequence: 21971483,
+ * //  Fee: '12',
+ * //  LastLedgerSequence: 21971503
+ * // }
+ * ```
+ */
+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: IssuedCurrencyAmount
+  /**
+   * 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
+}
+
+/**
+ * Verify the form and type of a TrustSet at runtime.
+ *
+ * @param tx - A TrustSet Transaction.
+ * @throws When the TrustSet is malformed.
+ */
+export function validateTrustSet(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+  const { LimitAmount, QualityIn, QualityOut } = tx
+
+  if (LimitAmount === undefined) {
+    throw new ValidationError('TrustSet: missing field LimitAmount')
+  }
+
+  if (!isAmount(LimitAmount)) {
+    throw new ValidationError('TrustSet: invalid LimitAmount')
+  }
+
+  if (QualityIn !== undefined && typeof QualityIn !== 'number') {
+    throw new ValidationError('TrustSet: QualityIn must be a number')
+  }
+
+  if (QualityOut !== undefined && typeof QualityOut !== 'number') {
+    throw new ValidationError('TrustSet: QualityOut must be a number')
+  }
+}

package/src/models/utils/flags.ts

@@ -0,0 +1,103 @@
+/* eslint-disable no-param-reassign -- param reassign is safe */
+/* eslint-disable no-bitwise -- flags require bitwise operations */
+
+import { ValidationError } from '../../errors'
+import {
+  AccountRootFlagsInterface,
+  AccountRootFlags,
+} from '../ledger/AccountRoot'
+import { AccountSetTfFlags } from '../transactions/accountSet'
+import { AMMDepositFlags } from '../transactions/AMMDeposit'
+import { AMMWithdrawFlags } from '../transactions/AMMWithdraw'
+import { GlobalFlags } from '../transactions/common'
+import { OfferCreateFlags } from '../transactions/offerCreate'
+import { PaymentFlags } from '../transactions/payment'
+import { PaymentChannelClaimFlags } from '../transactions/paymentChannelClaim'
+import type { Transaction } from '../transactions/transaction'
+import { TrustSetFlags } from '../transactions/trustSet'
+import { XChainModifyBridgeFlags } from '../transactions/XChainModifyBridge'
+
+import { isFlagEnabled } from '.'
+
+/**
+ * Convert an AccountRoot Flags number into an interface for easy interpretation.
+ *
+ * @param flags - A number which is the bitwise and of all enabled AccountRootFlagsInterface.
+ * @returns An interface with all flags as booleans.
+ */
+export function parseAccountRootFlags(
+  flags: number,
+): AccountRootFlagsInterface {
+  const flagsInterface: AccountRootFlagsInterface = {}
+
+  // If we use keys all will be strings and enums are reversed during transpilation
+  Object.values(AccountRootFlags).forEach((flag) => {
+    if (
+      typeof flag === 'string' &&
+      isFlagEnabled(flags, AccountRootFlags[flag])
+    ) {
+      flagsInterface[flag] = true
+    }
+  })
+
+  return flagsInterface
+}
+
+/**
+ * Sets a transaction's flags to its numeric representation.
+ *
+ * @param tx - A transaction to set its flags to its numeric representation.
+ */
+// eslint-disable-next-line complexity -- there's a lot of txs with flags
+export function setTransactionFlagsToNumber(tx: Transaction): void {
+  if (tx.Flags == null) {
+    tx.Flags = 0
+    return
+  }
+  if (typeof tx.Flags === 'number') {
+    return
+  }
+
+  switch (tx.TransactionType) {
+    case 'AccountSet':
+      tx.Flags = convertFlagsToNumber(tx.Flags, AccountSetTfFlags)
+      return
+    case 'AMMDeposit':
+      tx.Flags = convertFlagsToNumber(tx.Flags, AMMDepositFlags)
+      return
+    case 'AMMWithdraw':
+      tx.Flags = convertFlagsToNumber(tx.Flags, AMMWithdrawFlags)
+      return
+    case 'OfferCreate':
+      tx.Flags = convertFlagsToNumber(tx.Flags, OfferCreateFlags)
+      return
+    case 'PaymentChannelClaim':
+      tx.Flags = convertFlagsToNumber(tx.Flags, PaymentChannelClaimFlags)
+      return
+    case 'Payment':
+      tx.Flags = convertFlagsToNumber(tx.Flags, PaymentFlags)
+      return
+    case 'TrustSet':
+      tx.Flags = convertFlagsToNumber(tx.Flags, TrustSetFlags)
+      return
+    case 'XChainModifyBridge':
+      tx.Flags = convertFlagsToNumber(tx.Flags, XChainModifyBridgeFlags)
+      return
+    default:
+      tx.Flags = 0
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- added ValidationError check for flagEnum
+function convertFlagsToNumber(flags: GlobalFlags, flagEnum: any): number {
+  return Object.keys(flags).reduce((resultFlags, flag) => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- safe member access
+    if (flagEnum[flag] == null) {
+      throw new ValidationError(
+        `flag ${flag} doesn't exist in flagEnum: ${JSON.stringify(flagEnum)}`,
+      )
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- safe member access
+    return flags[flag] ? resultFlags | flagEnum[flag] : resultFlags
+  }, 0)
+}

package/src/models/utils/index.ts

@@ -0,0 +1,37 @@
+const HEX_REGEX = /^[0-9A-Fa-f]+$/u
+
+/**
+ * Verify that all fields of an object are in fields.
+ *
+ * @param obj - Object to verify fields.
+ * @param fields - Fields to verify.
+ * @returns True if keys in object are all in fields.
+ */
+export function onlyHasFields(
+  obj: Record<string, unknown>,
+  fields: string[],
+): boolean {
+  return Object.keys(obj).every((key: string) => fields.includes(key))
+}
+
+/**
+ * Perform bitwise AND (&) to check if a flag is enabled within Flags (as a number).
+ *
+ * @param Flags - A number that represents flags enabled.
+ * @param checkFlag - A specific flag to check if it's enabled within Flags.
+ * @returns True if checkFlag is enabled within Flags.
+ */
+export function isFlagEnabled(Flags: number, checkFlag: number): boolean {
+  // eslint-disable-next-line no-bitwise -- flags need bitwise
+  return (BigInt(checkFlag) & BigInt(Flags)) === BigInt(checkFlag)
+}
+
+/**
+ * Check if string is in hex format.
+ *
+ * @param str - The string to check if it's in hex format.
+ * @returns True if string is in hex format
+ */
+export function isHex(str: string): boolean {
+  return HEX_REGEX.test(str)
+}