xrpl 2.9.1 → 2.11.0

package/src/models/transactions/paymentChannelCreate.ts

@@ -0,0 +1,116 @@
+/* eslint-disable complexity -- Necessary for validatePaymentChannelCreate */
+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
+}
+
+/**
+ * Verify the form and type of an PaymentChannelCreate at runtime.
+ *
+ * @param tx - An PaymentChannelCreate Transaction.
+ * @throws When the PaymentChannelCreate is Malformed.
+ */
+// eslint-disable-next-line max-lines-per-function -- okay for this function, there's a lot of things to check
+export function validatePaymentChannelCreate(
+  tx: Record<string, unknown>,
+): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Amount === undefined) {
+    throw new ValidationError('PaymentChannelCreate: missing Amount')
+  }
+
+  if (typeof tx.Amount !== 'string') {
+    throw new ValidationError('PaymentChannelCreate: Amount must be a string')
+  }
+
+  if (tx.Destination === undefined) {
+    throw new ValidationError('PaymentChannelCreate: missing Destination')
+  }
+
+  if (typeof tx.Destination !== 'string') {
+    throw new ValidationError(
+      'PaymentChannelCreate: Destination must be a string',
+    )
+  }
+
+  if (tx.SettleDelay === undefined) {
+    throw new ValidationError('PaymentChannelCreate: missing SettleDelay')
+  }
+
+  if (typeof tx.SettleDelay !== 'number') {
+    throw new ValidationError(
+      'PaymentChannelCreate: SettleDelay must be a number',
+    )
+  }
+
+  if (tx.PublicKey === undefined) {
+    throw new ValidationError('PaymentChannelCreate: missing PublicKey')
+  }
+
+  if (typeof tx.PublicKey !== 'string') {
+    throw new ValidationError(
+      'PaymentChannelCreate: PublicKey must be a string',
+    )
+  }
+
+  if (tx.CancelAfter !== undefined && typeof tx.CancelAfter !== 'number') {
+    throw new ValidationError(
+      'PaymentChannelCreate: CancelAfter must be a number',
+    )
+  }
+
+  if (
+    tx.DestinationTag !== undefined &&
+    typeof tx.DestinationTag !== 'number'
+  ) {
+    throw new ValidationError(
+      'PaymentChannelCreate: DestinationTag must be a number',
+    )
+  }
+}

package/src/models/transactions/paymentChannelFund.ts

@@ -0,0 +1,65 @@
+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
+}
+
+/**
+ * Verify the form and type of an PaymentChannelFund at runtime.
+ *
+ * @param tx - An PaymentChannelFund Transaction.
+ * @throws When the PaymentChannelFund is Malformed.
+ */
+export function validatePaymentChannelFund(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Channel === undefined) {
+    throw new ValidationError('PaymentChannelFund: missing Channel')
+  }
+
+  if (typeof tx.Channel !== 'string') {
+    throw new ValidationError('PaymentChannelFund: Channel must be a string')
+  }
+
+  if (tx.Amount === undefined) {
+    throw new ValidationError('PaymentChannelFund: missing Amount')
+  }
+
+  if (typeof tx.Amount !== 'string') {
+    throw new ValidationError('PaymentChannelFund: Amount must be a string')
+  }
+
+  if (tx.Expiration !== undefined && typeof tx.Expiration !== 'number') {
+    throw new ValidationError('PaymentChannelFund: Expiration must be a number')
+  }
+}

package/src/models/transactions/setFee.ts

@@ -0,0 +1,48 @@
+import { BaseTransaction } from './common'
+
+export interface SetFeePreAmendment extends BaseTransaction {
+  /**
+   * The charge, in drops of XRP, for the reference transaction, as hex. (This is the transaction cost before scaling for load.)
+   */
+  BaseFee: string
+  /**
+   * The cost, in fee units, of the [reference transaction](https://xrpl.org/transaction-cost.html#reference-transaction-cost)
+   */
+  ReferenceFeeUnits: number
+  /**
+   * The base reserve, in drops
+   */
+  ReserveBase: number
+  /**
+   * The incremental reserve, in drops
+   */
+  ReserveIncrement: number
+}
+
+export interface SetFeePostAmendment extends BaseTransaction {
+  /**
+   * The charge, in drops of XRP, for the reference transaction. (This is the transaction cost before scaling for load.)
+   */
+  BaseFeeDrops: string
+  /**
+   * The base reserve, in drops
+   */
+  ReserveBaseDrops: string
+  /**
+   * The incremental reserve, in drops
+   */
+  ReserveIncrementDrops: string
+}
+
+/**
+ * Marks a change in transaction cost or reserve requirements as a result of Fee Voting.
+ *
+ * The output will be based on the status of the `XRPFees` amendment at the time of this transaction.
+ * - Before: {@link SetFeePostAmendment}
+ * - After: {@link SetFeePostAmendment}
+ *
+ * @category Pseudo Transaction Models
+ */
+export type SetFee = {
+  TransactionType: 'SetFee'
+} & (SetFeePreAmendment | SetFeePostAmendment)

package/src/models/transactions/setRegularKey.ts

@@ -0,0 +1,33 @@
+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
+}
+
+/**
+ * Verify the form and type of a SetRegularKey at runtime.
+ *
+ * @param tx - A SetRegularKey Transaction.
+ * @throws When the SetRegularKey is malformed.
+ */
+export function validateSetRegularKey(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.RegularKey !== undefined && typeof tx.RegularKey !== 'string') {
+    throw new ValidationError('SetRegularKey: RegularKey must be a string')
+  }
+}

package/src/models/transactions/signerListSet.ts

@@ -0,0 +1,89 @@
+import { ValidationError } from '../../errors'
+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 32 members. No address may appear more than once in the list, nor
+   * may the Account submitting the transaction appear in the list.
+   */
+  SignerEntries?: SignerEntry[]
+}
+
+const MAX_SIGNERS = 32
+
+const HEX_WALLET_LOCATOR_REGEX = /^[0-9A-Fa-f]{64}$/u
+
+/**
+ * Verify the form and type of an SignerListSet at runtime.
+ *
+ * @param tx - An SignerListSet Transaction.
+ * @throws When the SignerListSet is Malformed.
+ */
+// eslint-disable-next-line complexity -- validation can be complex
+export function validateSignerListSet(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.SignerQuorum === undefined) {
+    throw new ValidationError('SignerListSet: missing field SignerQuorum')
+  }
+
+  if (typeof tx.SignerQuorum !== 'number') {
+    throw new ValidationError('SignerListSet: invalid SignerQuorum')
+  }
+
+  // All other checks are for if SignerQuorum is greater than 0
+  if (tx.SignerQuorum === 0) {
+    return
+  }
+
+  if (tx.SignerEntries === undefined) {
+    throw new ValidationError('SignerListSet: missing field SignerEntries')
+  }
+
+  if (!Array.isArray(tx.SignerEntries)) {
+    throw new ValidationError('SignerListSet: invalid SignerEntries')
+  }
+
+  if (tx.SignerEntries.length === 0) {
+    throw new ValidationError(
+      'SignerListSet: need at least 1 member in SignerEntries',
+    )
+  }
+
+  if (tx.SignerEntries.length > MAX_SIGNERS) {
+    throw new ValidationError(
+      `SignerListSet: maximum of ${MAX_SIGNERS} members allowed in SignerEntries`,
+    )
+  }
+
+  for (const entry of tx.SignerEntries) {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Should be a SignerEntry
+    const signerEntry = entry as SignerEntry
+    const { WalletLocator } = signerEntry.SignerEntry
+    if (
+      WalletLocator !== undefined &&
+      !HEX_WALLET_LOCATOR_REGEX.test(WalletLocator)
+    ) {
+      throw new ValidationError(
+        `SignerListSet: WalletLocator in SignerEntry must be a 256-bit (32-byte) hexadecimal value`,
+      )
+    }
+  }
+}

package/src/models/transactions/ticketCreate.ts

@@ -0,0 +1,50 @@
+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
+}
+
+const MAX_TICKETS = 250
+
+/**
+ * Verify the form and type of a TicketCreate at runtime.
+ *
+ * @param tx - A TicketCreate Transaction.
+ * @throws When the TicketCreate is malformed.
+ */
+export function validateTicketCreate(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+  const { TicketCount } = tx
+
+  if (TicketCount === undefined) {
+    throw new ValidationError('TicketCreate: missing field TicketCount')
+  }
+
+  if (typeof TicketCount !== 'number') {
+    throw new ValidationError('TicketCreate: TicketCount must be a number')
+  }
+
+  if (
+    !Number.isInteger(TicketCount) ||
+    TicketCount < 1 ||
+    TicketCount > MAX_TICKETS
+  ) {
+    throw new ValidationError(
+      'TicketCreate: TicketCount must be an integer from 1 to 250',
+    )
+  }
+}

package/src/models/transactions/transaction.ts

@@ -0,0 +1,303 @@
+/* eslint-disable complexity -- verifies 19 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'
+
+/**
+ * @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
+
+/**
+ * @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
+
+    default:
+      throw new ValidationError(
+        `Invalid field TransactionType: ${tx.TransactionType}`,
+      )
+  }
+}