xrpl 2.10.0 → 2.12.0-beta.0

package/src/models/transactions/index.ts

@@ -0,0 +1,78 @@
+export { BaseTransaction } from './common'
+export { validate, TransactionAndMetadata, Transaction } from './transaction'
+export * from './metadata'
+export {
+  AccountSetAsfFlags,
+  AccountSetTfFlags,
+  AccountSetFlagsInterface,
+  AccountSet,
+} from './accountSet'
+export { AccountDelete } from './accountDelete'
+export { AMMBid } from './AMMBid'
+export { AMMDelete } from './AMMDelete'
+export {
+  AMMDepositFlags,
+  AMMDepositFlagsInterface,
+  AMMDeposit,
+} from './AMMDeposit'
+export { AMMCreate } from './AMMCreate'
+export { AMMVote } from './AMMVote'
+export {
+  AMMWithdrawFlags,
+  AMMWithdrawFlagsInterface,
+  AMMWithdraw,
+} from './AMMWithdraw'
+export { CheckCancel } from './checkCancel'
+export { CheckCash } from './checkCash'
+export { CheckCreate } from './checkCreate'
+export { Clawback } from './clawback'
+export { DepositPreauth } from './depositPreauth'
+export { EscrowCancel } from './escrowCancel'
+export { EscrowCreate } from './escrowCreate'
+export { EscrowFinish } from './escrowFinish'
+export { EnableAmendment, EnableAmendmentFlags } from './enableAmendment'
+export { NFTokenAcceptOffer } from './NFTokenAcceptOffer'
+export { NFTokenBurn } from './NFTokenBurn'
+export { NFTokenCancelOffer } from './NFTokenCancelOffer'
+export {
+  NFTokenCreateOffer,
+  NFTokenCreateOfferFlags,
+  NFTokenCreateOfferFlagsInterface,
+} from './NFTokenCreateOffer'
+export {
+  NFTokenMint,
+  NFTokenMintFlags,
+  NFTokenMintFlagsInterface,
+} from './NFTokenMint'
+export { OfferCancel } from './offerCancel'
+export {
+  OfferCreateFlags,
+  OfferCreateFlagsInterface,
+  OfferCreate,
+} from './offerCreate'
+export { PaymentFlags, PaymentFlagsInterface, Payment } from './payment'
+export {
+  PaymentChannelClaimFlags,
+  PaymentChannelClaimFlagsInterface,
+  PaymentChannelClaim,
+} from './paymentChannelClaim'
+export { PaymentChannelCreate } from './paymentChannelCreate'
+export { PaymentChannelFund } from './paymentChannelFund'
+export { SetFee, SetFeePreAmendment, SetFeePostAmendment } from './setFee'
+export { SetRegularKey } from './setRegularKey'
+export { SignerListSet } from './signerListSet'
+export { TicketCreate } from './ticketCreate'
+export { TrustSetFlagsInterface, TrustSetFlags, TrustSet } from './trustSet'
+export { UNLModify } from './UNLModify'
+export { XChainAddAccountCreateAttestation } from './XChainAddAccountCreateAttestation'
+export { XChainAddClaimAttestation } from './XChainAddClaimAttestation'
+export { XChainClaim } from './XChainClaim'
+export { XChainCommit } from './XChainCommit'
+export { XChainCreateBridge } from './XChainCreateBridge'
+export { XChainCreateClaimID } from './XChainCreateClaimID'
+export { XChainAccountCreateCommit } from './XChainAccountCreateCommit'
+export {
+  XChainModifyBridge,
+  XChainModifyBridgeFlags,
+  XChainModifyBridgeFlagsInterface,
+} from './XChainModifyBridge'

package/src/models/transactions/metadata.ts

@@ -0,0 +1,69 @@
+import { Amount } from '../common'
+
+export interface CreatedNode {
+  CreatedNode: {
+    LedgerEntryType: string
+    LedgerIndex: string
+    NewFields: { [field: string]: unknown }
+  }
+}
+
+export interface ModifiedNode {
+  ModifiedNode: {
+    LedgerEntryType: string
+    LedgerIndex: string
+    FinalFields?: { [field: string]: unknown }
+    PreviousFields?: { [field: string]: unknown }
+    PreviousTxnID?: string
+    PreviousTxnLgrSeq?: number
+  }
+}
+
+export interface DeletedNode {
+  DeletedNode: {
+    LedgerEntryType: string
+    LedgerIndex: string
+    FinalFields: { [field: string]: unknown }
+  }
+}
+
+export type Node = CreatedNode | ModifiedNode | DeletedNode
+
+/**
+ * A typeguard to check if a node is a CreatedNode.
+ *
+ * @param node - A node from metadata.
+ * @returns whether the given node is a CreatedNode.
+ */
+export function isCreatedNode(node: Node): node is CreatedNode {
+  return Object.prototype.hasOwnProperty.call(node, `CreatedNode`)
+}
+
+/**
+ * A typeguard to check if a node is a ModifiedNode.
+ *
+ * @param node - A node from metadata.
+ * @returns whether the given node is a ModifiedNode.
+ */
+export function isModifiedNode(node: Node): node is ModifiedNode {
+  return Object.prototype.hasOwnProperty.call(node, `ModifiedNode`)
+}
+
+/**
+ * A typeguard to check if a node is a DeletedNode.
+ *
+ * @param node - A node from metadata.
+ * @returns whether the given node is a DeletedNode.
+ */
+export function isDeletedNode(node: Node): node is DeletedNode {
+  return Object.prototype.hasOwnProperty.call(node, `DeletedNode`)
+}
+
+export interface TransactionMetadata {
+  AffectedNodes: Node[]
+  DeliveredAmount?: Amount
+  // "unavailable" possible for transactions before 2014-01-20
+  delivered_amount?: Amount | 'unavailable'
+  TransactionIndex: number
+  TransactionResult: string
+}

package/src/models/transactions/offerCancel.ts

@@ -0,0 +1,37 @@
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * An OfferCancel transaction removes an Offer object from the XRP Ledger.
+ *
+ *  @category Transaction Models
+ */
+export interface OfferCancel extends BaseTransaction {
+  TransactionType: 'OfferCancel'
+  /**
+   * The sequence number (or Ticket number) of a previous OfferCreate
+   * transaction. If specified, cancel any offer object in the ledger that was
+   * created by that transaction. It is not considered an error if the offer.
+   * specified does not exist.
+   */
+  OfferSequence: number
+}
+
+/**
+ * Verify the form and type of an OfferCancel at runtime.
+ *
+ * @param tx - An OfferCancel Transaction.
+ * @throws When the OfferCancel is Malformed.
+ */
+export function validateOfferCancel(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.OfferSequence === undefined) {
+    throw new ValidationError('OfferCancel: missing field OfferSequence')
+  }
+
+  if (typeof tx.OfferSequence !== 'number') {
+    throw new ValidationError('OfferCancel: OfferSequence must be a number')
+  }
+}

package/src/models/transactions/offerCreate.ts

@@ -0,0 +1,144 @@
+/* eslint-disable complexity -- Necessary for validateOfferCreate */
+import { ValidationError } from '../../errors'
+import { Amount } from '../common'
+
+import {
+  BaseTransaction,
+  GlobalFlags,
+  validateBaseTransaction,
+  isAmount,
+} from './common'
+
+/**
+ * Transaction Flags for an OfferCreate Transaction.
+ *
+ * @category Transaction Flags
+ */
+export enum OfferCreateFlags {
+  /**
+   * If enabled, the offer does not consume offers that exactly match it, and
+   * instead becomes an Offer object in the ledger. It still consumes offers
+   * that cross it.
+   */
+  tfPassive = 0x00010000,
+  /**
+   * Treat the offer as an Immediate or Cancel order. If enabled, the offer
+   * never becomes a ledger object: it only tries to match existing offers in
+   * the ledger. If the offer cannot match any offers immediately, it executes
+   * "successfully" without trading any currency. In this case, the transaction
+   * has the result code tesSUCCESS, but creates no Offer objects in the ledger.
+   */
+  tfImmediateOrCancel = 0x00020000,
+  /**
+   * Treat the offer as a Fill or Kill order . Only try to match existing
+   * offers in the ledger, and only do so if the entire TakerPays quantity can
+   * be obtained. If the fix1578 amendment is enabled and the offer cannot be
+   * executed when placed, the transaction has the result code tecKILLED;
+   * otherwise, the transaction uses the result code tesSUCCESS even when it was
+   * killed without trading any currency.
+   */
+  tfFillOrKill = 0x00040000,
+  /**
+   * Exchange the entire TakerGets amount, even if it means obtaining more than
+   * the TakerPays amount in exchange.
+   */
+  tfSell = 0x00080000,
+}
+
+/**
+ * Map of flags to boolean values representing {@link OfferCreate} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ *
+ * @example
+ * ```typescript
+ * const tx: OfferCreate = {
+ * Account: 'rhFcpWDHLqpBmX4ezWiA5VLSS4e1BHqhHd',
+ * TakerGets: '43000.51',
+ * TakerPays: '12928290425',
+ * TransactionType: 'OfferCreate',
+ * Flags: {
+ *   tfPassive: true,
+ *   tfFillOrKill: true,
+ *  },
+ * }
+ *
+ * // Autofill the tx to see how flags actually look compared to the interface usage.
+ * const autofilledTx = await client.autofill(tx)
+ * console.log(autofilledTx)
+ * // {
+ * // Account: 'rhFcpWDHLqpBmX4ezWiA5VLSS4e1BHqhHd',
+ * // TakerGets: '43000.51',
+ * // TakerPays: '12928290425',
+ * // TransactionType: 'OfferCreate',
+ * // Flags: 327680,
+ * // Sequence: 21970384,
+ * // Fee: '12',
+ * // LastLedgerSequence: 21970404
+ * // }
+ * ```
+ */
+export interface OfferCreateFlagsInterface extends GlobalFlags {
+  tfPassive?: boolean
+  tfImmediateOrCancel?: boolean
+  tfFillOrKill?: boolean
+  tfSell?: boolean
+}
+
+/**
+ * An OfferCreate transaction is effectively a limit order . It defines an
+ * intent to exchange currencies, and creates an Offer object if not completely.
+ * Fulfilled when placed. Offers can be partially fulfilled.
+ *
+ * @category Transaction Models
+ */
+export interface OfferCreate extends BaseTransaction {
+  TransactionType: 'OfferCreate'
+  Flags?: number | OfferCreateFlagsInterface
+  /**
+   * Time after which the offer is no longer active, in seconds since the.
+   * Ripple Epoch.
+   */
+  Expiration?: number
+  /** An offer to delete first, specified in the same way as OfferCancel. */
+  OfferSequence?: number
+  /** The amount and type of currency being provided by the offer creator. */
+  TakerGets: Amount
+  /** The amount and type of currency being requested by the offer creator. */
+  TakerPays: Amount
+}
+
+/**
+ * Verify the form and type of an OfferCreate at runtime.
+ *
+ * @param tx - An OfferCreate Transaction.
+ * @throws When the OfferCreate is Malformed.
+ */
+export function validateOfferCreate(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.TakerGets === undefined) {
+    throw new ValidationError('OfferCreate: missing field TakerGets')
+  }
+
+  if (tx.TakerPays === undefined) {
+    throw new ValidationError('OfferCreate: missing field TakerPays')
+  }
+
+  if (typeof tx.TakerGets !== 'string' && !isAmount(tx.TakerGets)) {
+    throw new ValidationError('OfferCreate: invalid TakerGets')
+  }
+
+  if (typeof tx.TakerPays !== 'string' && !isAmount(tx.TakerPays)) {
+    throw new ValidationError('OfferCreate: invalid TakerPays')
+  }
+
+  if (tx.Expiration !== undefined && typeof tx.Expiration !== 'number') {
+    throw new ValidationError('OfferCreate: invalid Expiration')
+  }
+
+  if (tx.OfferSequence !== undefined && typeof tx.OfferSequence !== 'number') {
+    throw new ValidationError('OfferCreate: invalid OfferSequence')
+  }
+}

package/src/models/transactions/payment.ts

@@ -0,0 +1,278 @@
+/* eslint-disable complexity -- Necessary for validatePayment */
+import { ValidationError } from '../../errors'
+import { Amount, Path } from '../common'
+import { isFlagEnabled } from '../utils'
+
+import {
+  BaseTransaction,
+  isAmount,
+  GlobalFlags,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * Enum representing values for Payment Transaction Flags.
+ *
+ * @category Transaction Flags
+ */
+export enum PaymentFlags {
+  /**
+   * Do not use the default path; only use paths included in the Paths field.
+   * This is intended to force the transaction to take arbitrage opportunities.
+   * Most clients do not need this.
+   */
+  tfNoDirectRipple = 0x00010000,
+  /**
+   * If the specified Amount cannot be sent without spending more than SendMax,
+   * reduce the received amount instead of failing outright. See Partial.
+   * Payments for more details.
+   */
+  tfPartialPayment = 0x00020000,
+  /**
+   * Only take paths where all the conversions have an input:output ratio that
+   * is equal or better than the ratio of Amount:SendMax. See Limit Quality for
+   * details.
+   */
+  tfLimitQuality = 0x00040000,
+}
+
+/**
+ * Map of flags to boolean values representing {@link Payment} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ *
+ * @example
+ * ```typescript
+ * const partialPayment: Payment = {
+ *  TransactionType: 'Payment',
+ *  Account: 'rM9WCfJU6udpFkvKThRaFHDMsp7L8rpgN',
+ *  Amount: {
+ *    currency: 'FOO',
+ *    value: '4000',
+ *    issuer: 'rPzwM2JfCSDjhbesdTCqFjWWdK7eFtTwZz',
+ *  },
+ *  Destination: 'rPzwM2JfCSDjhbesdTCqFjWWdK7eFtTwZz',
+ *  Flags: {
+ *    tfPartialPayment: true
+ *  }
+ * }
+ *
+ * // Autofill the tx to see how flags actually look compared to the interface usage.
+ * const autofilledTx = await client.autofill(partialPayment)
+ * console.log(autofilledTx)
+ * // {
+ * //  TransactionType: 'Payment',
+ * //  Account: 'rM9WCfJU6udpFkvKThRaFHDMsp7L8rpgN',
+ * //  Amount: {
+ * //   currency: 'FOO',
+ * //   value: '4000',
+ * //   issuer: 'rPzwM2JfCSDjhbesdTCqFjWWdK7eFtTwZz'
+ * //  },
+ * //  Destination: 'rPzwM2JfCSDjhbesdTCqFjWWdK7eFtTwZz',
+ * //  Flags: 131072,
+ * //  Sequence: 21970996,
+ * //  Fee: '12',
+ * //  LastLedgerSequence: 21971016
+ * // }
+ * ```
+ */
+export interface PaymentFlagsInterface extends GlobalFlags {
+  /**
+   * Do not use the default path; only use paths included in the Paths field.
+   * This is intended to force the transaction to take arbitrage opportunities.
+   * Most clients do not need this.
+   */
+  tfNoDirectRipple?: boolean
+  /**
+   * If the specified Amount cannot be sent without spending more than SendMax,
+   * reduce the received amount instead of failing outright. See Partial.
+   * Payments for more details.
+   */
+  tfPartialPayment?: boolean
+  /**
+   * Only take paths where all the conversions have an input:output ratio that
+   * is equal or better than the ratio of Amount:SendMax. See Limit Quality for
+   * details.
+   */
+  tfLimitQuality?: boolean
+}
+
+/**
+ * A Payment transaction represents a transfer of value from one account to
+ * another.
+ *
+ * @category Transaction Models
+ */
+export interface Payment extends BaseTransaction {
+  TransactionType: 'Payment'
+  /**
+   * The amount of currency to deliver. For non-XRP amounts, the nested field
+   * names MUST be lower-case. If the tfPartialPayment flag is set, deliver up
+   * to this amount instead.
+   */
+  Amount: Amount
+  /** The unique address of the account receiving the payment. */
+  Destination: string
+  /**
+   * Arbitrary tag that identifies the reason for the payment to the
+   * destination, or a hosted recipient to pay.
+   */
+  DestinationTag?: number
+  /**
+   * Arbitrary 256-bit hash representing a specific reason or identifier for
+   * this payment.
+   */
+  InvoiceID?: string
+  /**
+   * Array of payment paths to be used for this transaction. Must be omitted
+   * for XRP-to-XRP transactions.
+   */
+  Paths?: Path[]
+  /**
+   * Highest amount of source currency this transaction is allowed to cost,
+   * including transfer fees, exchange rates, and slippage . Does not include
+   * the XRP destroyed as a cost for submitting the transaction. For non-XRP
+   * amounts, the nested field names MUST be lower-case. Must be supplied for
+   * cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP
+   * Payments.
+   */
+  SendMax?: Amount
+  /**
+   * Minimum amount of destination currency this transaction should deliver.
+   * Only valid if this is a partial payment. For non-XRP amounts, the nested
+   * field names are lower-case.
+   */
+  DeliverMin?: Amount
+  Flags?: number | PaymentFlagsInterface
+}
+
+/**
+ * Verify the form and type of a Payment at runtime.
+ *
+ * @param tx - A Payment Transaction.
+ * @throws When the Payment is malformed.
+ */
+export function validatePayment(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Amount === undefined) {
+    throw new ValidationError('PaymentTransaction: missing field Amount')
+  }
+
+  if (!isAmount(tx.Amount)) {
+    throw new ValidationError('PaymentTransaction: invalid Amount')
+  }
+
+  if (tx.Destination === undefined) {
+    throw new ValidationError('PaymentTransaction: missing field Destination')
+  }
+
+  if (!isAmount(tx.Destination)) {
+    throw new ValidationError('PaymentTransaction: invalid Destination')
+  }
+
+  if (tx.DestinationTag != null && typeof tx.DestinationTag !== 'number') {
+    throw new ValidationError(
+      'PaymentTransaction: DestinationTag must be a number',
+    )
+  }
+
+  if (tx.InvoiceID !== undefined && typeof tx.InvoiceID !== 'string') {
+    throw new ValidationError('PaymentTransaction: InvoiceID must be a string')
+  }
+
+  if (
+    tx.Paths !== undefined &&
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
+    !isPaths(tx.Paths as Array<Array<Record<string, unknown>>>)
+  ) {
+    throw new ValidationError('PaymentTransaction: invalid Paths')
+  }
+
+  if (tx.SendMax !== undefined && !isAmount(tx.SendMax)) {
+    throw new ValidationError('PaymentTransaction: invalid SendMax')
+  }
+
+  checkPartialPayment(tx)
+}
+
+function checkPartialPayment(tx: Record<string, unknown>): void {
+  if (tx.DeliverMin != null) {
+    if (tx.Flags == null) {
+      throw new ValidationError(
+        'PaymentTransaction: tfPartialPayment flag required with DeliverMin',
+      )
+    }
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
+    const flags = tx.Flags as number | PaymentFlagsInterface
+    const isTfPartialPayment =
+      typeof flags === 'number'
+        ? isFlagEnabled(flags, PaymentFlags.tfPartialPayment)
+        : flags.tfPartialPayment ?? false
+
+    if (!isTfPartialPayment) {
+      throw new ValidationError(
+        'PaymentTransaction: tfPartialPayment flag required with DeliverMin',
+      )
+    }
+
+    if (!isAmount(tx.DeliverMin)) {
+      throw new ValidationError('PaymentTransaction: invalid DeliverMin')
+    }
+  }
+}
+
+function isPathStep(pathStep: Record<string, unknown>): boolean {
+  if (pathStep.account !== undefined && typeof pathStep.account !== 'string') {
+    return false
+  }
+  if (
+    pathStep.currency !== undefined &&
+    typeof pathStep.currency !== 'string'
+  ) {
+    return false
+  }
+  if (pathStep.issuer !== undefined && typeof pathStep.issuer !== 'string') {
+    return false
+  }
+  if (
+    pathStep.account !== undefined &&
+    pathStep.currency === undefined &&
+    pathStep.issuer === undefined
+  ) {
+    return true
+  }
+  if (pathStep.currency !== undefined || pathStep.issuer !== undefined) {
+    return true
+  }
+  return false
+}
+
+function isPath(path: Array<Record<string, unknown>>): boolean {
+  for (const pathStep of path) {
+    if (!isPathStep(pathStep)) {
+      return false
+    }
+  }
+  return true
+}
+
+function isPaths(paths: Array<Array<Record<string, unknown>>>): boolean {
+  if (!Array.isArray(paths) || paths.length === 0) {
+    return false
+  }
+
+  for (const path of paths) {
+    if (!Array.isArray(path) || path.length === 0) {
+      return false
+    }
+
+    if (!isPath(path)) {
+      return false
+    }
+  }
+
+  return true
+}