xrpl 2.10.0 → 2.11.0

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
+}

package/src/models/transactions/paymentChannelClaim.ts

@@ -0,0 +1,165 @@
+/* eslint-disable complexity -- Necessary for validatePaymentChannelClaim */
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, GlobalFlags, validateBaseTransaction } from './common'
+
+/**
+ * Enum representing values for PaymentChannelClaim transaction flags.
+ *
+ * @category Transaction Flags
+ */
+export enum PaymentChannelClaimFlags {
+  /**
+   * Clear the channel's Expiration time. (Expiration is different from the
+   * channel's immutable CancelAfter time.) Only the source address of the
+   * payment channel can use this flag.
+   */
+  tfRenew = 0x00010000,
+  /**
+   * Request to close the channel. Only the channel source and destination
+   * addresses can use this flag. This flag closes the channel immediately if it
+   * has no more XRP allocated to it after processing the current claim, or if
+   * the destination address uses it. If the source address uses this flag when
+   * the channel still holds XRP, this schedules the channel to close after
+   * SettleDelay seconds have passed. (Specifically, this sets the Expiration of
+   * the channel to the close time of the previous ledger plus the channel's
+   * SettleDelay time, unless the channel already has an earlier Expiration
+   * time.) If the destination address uses this flag when the channel still
+   * holds XRP, any XRP that remains after processing the claim is returned to
+   * the source address.
+   */
+  tfClose = 0x00020000,
+}
+
+/**
+ * Map of flags to boolean values representing {@link PaymentChannelClaim}
+ * transaction flags.
+ *
+ * @category Transaction Flags
+ *
+ * @example
+ * ```typescript
+ * const paymentChannelClaim: PaymentChannelClaim = {
+ *  Account: 'rMpxZpuy5RBSP47oK2hDWUtk3B5BNQHfGj,
+ *  TransactionType: 'PaymentChannelClaim',
+ *  Channel: hashes.hashPaymentChannel(
+ *    'rMpxZpuy5RBSP47oK2hDWUtk3B5BNQHfGj',
+ *    'rQGYqiyH5Ue9J96p4E6Qt6AvqxK4sDhnS5',
+ *    21970712,
+ *  ),
+ *  Amount: '100',
+ *  Flags: {
+ *    tfClose: true
+ *  }
+ *}
+ *
+ * // Autofill the tx to see how flags actually look compared to the interface usage.
+ * const autofilledTx = await client.autofill(paymentChannelClaim)
+ * console.log(autofilledTx)
+ * // {
+ * //  Account: 'rMpxZpuy5RBSP47oK2hDWUtk3B5BNQHfGj',
+ * //  TransactionType: 'PaymentChannelClaim',
+ * //  Channel: 'FC14BF9245D731DC1749EE0F070765E4EB4E993F8ECEE3D00F7E6E26D6EF98CF',
+ * //  Amount: '100',
+ * //  Flags: 131072,
+ * //  Sequence: 21970713,
+ * //  Fee: '12',
+ * //  LastLedgerSequence: 21970658
+ * // }
+ * ```
+ */
+export interface PaymentChannelClaimFlagsInterface extends GlobalFlags {
+  /**
+   * Clear the channel's Expiration time. (Expiration is different from the
+   * channel's immutable CancelAfter time.) Only the source address of the
+   * payment channel can use this flag.
+   */
+  tfRenew?: boolean
+  /**
+   * Request to close the channel. Only the channel source and destination
+   * addresses can use this flag. This flag closes the channel immediately if it
+   * has no more XRP allocated to it after processing the current claim, or if
+   * the destination address uses it. If the source address uses this flag when
+   * the channel still holds XRP, this schedules the channel to close after
+   * SettleDelay seconds have passed. (Specifically, this sets the Expiration of
+   * the channel to the close time of the previous ledger plus the channel's
+   * SettleDelay time, unless the channel already has an earlier Expiration
+   * time.) If the destination address uses this flag when the channel still
+   * holds XRP, any XRP that remains after processing the claim is returned to
+   * the source address.
+   */
+  tfClose?: boolean
+}
+
+/**
+ * Claim XRP from a payment channel, adjust the payment channel's expiration,
+ * or both.
+ *
+ * @category Transaction Models
+ */
+export interface PaymentChannelClaim extends BaseTransaction {
+  TransactionType: 'PaymentChannelClaim'
+  Flags?: number | PaymentChannelClaimFlagsInterface
+  /** The unique ID of the channel as a 64-character hexadecimal string. */
+  Channel: string
+  /**
+   * Total amount of XRP, in drops, delivered by this channel after processing
+   * this claim. Required to deliver XRP. Must be more than the total amount
+   * delivered by the channel so far, but not greater than the Amount of the
+   * signed claim. Must be provided except when closing the channel.
+   */
+  Balance?: string
+  /**
+   * The amount of XRP, in drops, authorized by the Signature. This must match
+   * the amount in the signed message. This is the cumulative amount of XRP that
+   * can be dispensed by the channel, including XRP previously redeemed.
+   */
+  Amount?: string
+  /**
+   * The signature of this claim, as hexadecimal. The signed message contains
+   * the channel ID and the amount of the claim. Required unless the sender of
+   * the transaction is the source address of the channel.
+   */
+  Signature?: string
+  /**
+   * The public key used for the signature, as hexadecimal. This must match the
+   * PublicKey stored in the ledger for the channel. Required unless the sender
+   * of the transaction is the source address of the channel and the Signature
+   * field is omitted.
+   */
+  PublicKey?: string
+}
+
+/**
+ * Verify the form and type of an PaymentChannelClaim at runtime.
+ *
+ * @param tx - An PaymentChannelClaim Transaction.
+ * @throws When the PaymentChannelClaim is Malformed.
+ */
+export function validatePaymentChannelClaim(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Channel === undefined) {
+    throw new ValidationError('PaymentChannelClaim: missing Channel')
+  }
+
+  if (typeof tx.Channel !== 'string') {
+    throw new ValidationError('PaymentChannelClaim: Channel must be a string')
+  }
+
+  if (tx.Balance !== undefined && typeof tx.Balance !== 'string') {
+    throw new ValidationError('PaymentChannelClaim: Balance must be a string')
+  }
+
+  if (tx.Amount !== undefined && typeof tx.Amount !== 'string') {
+    throw new ValidationError('PaymentChannelClaim: Amount must be a string')
+  }
+
+  if (tx.Signature !== undefined && typeof tx.Signature !== 'string') {
+    throw new ValidationError('PaymentChannelClaim: Signature must be a string')
+  }
+
+  if (tx.PublicKey !== undefined && typeof tx.PublicKey !== 'string') {
+    throw new ValidationError('PaymentChannelClaim: PublicKey must be a string')
+  }
+}