xrpl 2.10.0 → 2.11.0

package/src/models/transactions/accountSet.ts

@@ -0,0 +1,228 @@
+/* eslint-disable complexity -- Necessary for validateAccountSet */
+
+import { isValidClassicAddress } from 'ripple-address-codec'
+
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * Enum for AccountSet Flags.
+ *
+ * @category Transaction Flags
+ */
+export enum AccountSetAsfFlags {
+  /** Require a destination tag to send transactions to this account. */
+  asfRequireDest = 1,
+  /**
+   * Require authorization for users to hold balances issued by this address
+   * can only be enabled if the address has no trust lines connected to it.
+   */
+  asfRequireAuth = 2,
+  /** XRP should not be sent to this account. */
+  asfDisallowXRP = 3,
+  /**
+   * Disallow use of the master key pair. Can only be enabled if the account
+   * has configured another way to sign transactions, such as a Regular Key or a
+   * Signer List.
+   */
+  asfDisableMaster = 4,
+  /**
+   * Track the ID of this account's most recent transaction. Required for
+   * AccountTxnID.
+   */
+  asfAccountTxnID = 5,
+  /**
+   * Permanently give up the ability to freeze individual trust lines or
+   * disable Global Freeze. This flag can never be disabled after being enabled.
+   */
+  asfNoFreeze = 6,
+  /** Freeze all assets issued by this account. */
+  asfGlobalFreeze = 7,
+  /** Enable rippling on this account's trust lines by default. */
+  asfDefaultRipple = 8,
+  /** Enable Deposit Authorization on this account. */
+  asfDepositAuth = 9,
+  /**
+   * Allow another account to mint and burn tokens on behalf of this account.
+   */
+  asfAuthorizedNFTokenMinter = 10,
+  /** asf 11 is reserved for Hooks amendment */
+  /** Disallow other accounts from creating incoming NFTOffers */
+  asfDisallowIncomingNFTokenOffer = 12,
+  /** Disallow other accounts from creating incoming Checks */
+  asfDisallowIncomingCheck = 13,
+  /** Disallow other accounts from creating incoming PayChannels */
+  asfDisallowIncomingPayChan = 14,
+  /** Disallow other accounts from creating incoming Trustlines */
+  asfDisallowIncomingTrustline = 15,
+  /** Permanently gain the ability to claw back issued IOUs */
+  asfAllowTrustLineClawback = 16,
+}
+
+/**
+ * Enum for AccountSet Transaction Flags.
+ *
+ * @category Transaction Flags
+ */
+export enum AccountSetTfFlags {
+  /** The same as SetFlag: asfRequireDest. */
+  tfRequireDestTag = 0x00010000,
+  /** The same as ClearFlag: asfRequireDest. */
+  tfOptionalDestTag = 0x00020000,
+  /** The same as SetFlag: asfRequireAuth. */
+  tfRequireAuth = 0x00040000,
+  /** The same as ClearFlag: asfRequireAuth. */
+  tfOptionalAuth = 0x00080000,
+  /** The same as SetFlag: asfDisallowXRP. */
+  tfDisallowXRP = 0x00100000,
+  /** The same as ClearFlag: asfDisallowXRP. */
+  tfAllowXRP = 0x00200000,
+}
+
+/**
+ * Map of flags to boolean values representing {@link AccountSet} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ *
+ * @example
+ * ```typescript
+ *  const accountSetTx: AccountSet = {
+ *    TransactionType: 'AccountSet',
+ *    Account: 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn',
+ *    Flags: {
+ *      tfOptionalDestTag: true,
+ *      tfRequireAuth: true
+ *    },
+ *  }
+ *
+ * // Autofill the tx to see how flags actually look compared to the interface usage.
+ * const autofilledTx = await client.autofill(accountSetTx)
+ * console.log(autofilledTx)
+ * // {
+ * //  TransactionType: 'AccountSet',
+ * //  Account: 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn',
+ * //  Flags: 393216,
+ * //  Sequence: 1,
+ * //  Fee: '12',
+ * //  LastLedgerSequence: 21971793
+ * // }
+ * ```
+ */
+export interface AccountSetFlagsInterface {
+  tfRequireDestTag?: boolean
+  tfOptionalDestTag?: boolean
+  tfRequireAuth?: boolean
+  tfOptionalAuth?: boolean
+  tfDisallowXRP?: boolean
+  tfAllowXRP?: boolean
+}
+
+/**
+ * An AccountSet transaction modifies the properties of an account in the XRP
+ * Ledger.
+ *
+ * @category Transaction Models
+ */
+export interface AccountSet extends BaseTransaction {
+  TransactionType: 'AccountSet'
+  Flags?: number | AccountSetFlagsInterface
+  /** Unique identifier of a flag to disable for this account. */
+  ClearFlag?: number
+  /**
+   * The domain that owns this account, as a string of hex representing the.
+   * ASCII for the domain in lowercase.
+   */
+  Domain?: string
+  /** Hash of an email address to be used for generating an avatar image. */
+  EmailHash?: string
+  /** Public key for sending encrypted messages to this account. */
+  MessageKey?: string
+  /** Integer flag to enable for this account. */
+  SetFlag?: AccountSetAsfFlags
+  /**
+   * The fee to charge when users transfer this account's issued currencies,
+   * represented as billionths of a unit. Cannot be more than 2000000000 or less
+   * than 1000000000, except for the special case 0 meaning no fee.
+   */
+  TransferRate?: number
+  /**
+   * Tick size to use for offers involving a currency issued by this address.
+   * The exchange rates of those offers is rounded to this many significant
+   * digits. Valid values are 3 to 15 inclusive, or 0 to disable.
+   */
+  TickSize?: number
+  /**
+   * Sets an alternate account that is allowed to mint NFTokens on this
+   * account's behalf using NFTokenMint's `Issuer` field.
+   */
+  NFTokenMinter?: string
+}
+
+const MIN_TICK_SIZE = 3
+const MAX_TICK_SIZE = 15
+
+/**
+ * Verify the form and type of an AccountSet at runtime.
+ *
+ * @param tx - An AccountSet Transaction.
+ * @throws When the AccountSet is Malformed.
+ */
+// eslint-disable-next-line max-lines-per-function, max-statements -- okay for this method, only a little over
+export function validateAccountSet(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (
+    tx.NFTokenMinter !== undefined &&
+    !isValidClassicAddress(String(tx.NFTokenMinter))
+  ) {
+    throw new ValidationError('AccountSet: invalid NFTokenMinter')
+  }
+
+  if (tx.ClearFlag !== undefined) {
+    if (typeof tx.ClearFlag !== 'number') {
+      throw new ValidationError('AccountSet: invalid ClearFlag')
+    }
+    if (!Object.values(AccountSetAsfFlags).includes(tx.ClearFlag)) {
+      throw new ValidationError('AccountSet: invalid ClearFlag')
+    }
+  }
+
+  if (tx.Domain !== undefined && typeof tx.Domain !== 'string') {
+    throw new ValidationError('AccountSet: invalid Domain')
+  }
+
+  if (tx.EmailHash !== undefined && typeof tx.EmailHash !== 'string') {
+    throw new ValidationError('AccountSet: invalid EmailHash')
+  }
+
+  if (tx.MessageKey !== undefined && typeof tx.MessageKey !== 'string') {
+    throw new ValidationError('AccountSet: invalid MessageKey')
+  }
+
+  if (tx.SetFlag !== undefined) {
+    if (typeof tx.SetFlag !== 'number') {
+      throw new ValidationError('AccountSet: invalid SetFlag')
+    }
+    if (!Object.values(AccountSetAsfFlags).includes(tx.SetFlag)) {
+      throw new ValidationError('AccountSet: invalid SetFlag')
+    }
+  }
+
+  if (tx.TransferRate !== undefined && typeof tx.TransferRate !== 'number') {
+    throw new ValidationError('AccountSet: invalid TransferRate')
+  }
+
+  if (tx.TickSize !== undefined) {
+    if (typeof tx.TickSize !== 'number') {
+      throw new ValidationError('AccountSet: invalid TickSize')
+    }
+    if (
+      tx.TickSize !== 0 &&
+      (tx.TickSize < MIN_TICK_SIZE || tx.TickSize > MAX_TICK_SIZE)
+    ) {
+      throw new ValidationError('AccountSet: invalid TickSize')
+    }
+  }
+}

package/src/models/transactions/checkCancel.ts

@@ -0,0 +1,34 @@
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * Cancels an unredeemed Check, removing it from the ledger without sending any
+ * money. The source or the destination of the check can cancel a Check at any
+ * time using this transaction type. If the Check has expired, any address can
+ * cancel it.
+ *
+ * @category Transaction Models
+ */
+export interface CheckCancel extends BaseTransaction {
+  TransactionType: 'CheckCancel'
+  /**
+   * The ID of the Check ledger object to cancel as a 64-character hexadecimal
+   * string.
+   */
+  CheckID: string
+}
+
+/**
+ * Verify the form and type of an CheckCancel at runtime.
+ *
+ * @param tx - An CheckCancel Transaction.
+ * @throws When the CheckCancel is Malformed.
+ */
+export function validateCheckCancel(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.CheckID !== undefined && typeof tx.CheckID !== 'string') {
+    throw new ValidationError('CheckCancel: invalid CheckID')
+  }
+}

package/src/models/transactions/checkCash.ts

@@ -0,0 +1,73 @@
+/* eslint-disable complexity -- Necessary for validateCheckCash */
+import { ValidationError } from '../../errors'
+import { Amount } from '../common'
+
+import { BaseTransaction, validateBaseTransaction, isAmount } from './common'
+
+/**
+ * Attempts to redeem a Check object in the ledger to receive up to the amount
+ * authorized by the corresponding CheckCreate transaction. Only the Destination
+ * address of a Check can cash it with a CheckCash transaction.
+ *
+ * @category Transaction Models
+ */
+export interface CheckCash extends BaseTransaction {
+  TransactionType: 'CheckCash'
+  /**
+   * The ID of the Check ledger object to cash as a 64-character hexadecimal
+   * string.
+   */
+  CheckID: string
+  /**
+   * Redeem the Check for exactly this amount, if possible. The currency must
+   * match that of the SendMax of the corresponding CheckCreate transaction. You.
+   * must provide either this field or DeliverMin.
+   */
+  Amount?: Amount
+  /**
+   * Redeem the Check for at least this amount and for as much as possible. The
+   * currency must match that of the SendMax of the corresponding CheckCreate.
+   * transaction. You must provide either this field or Amount.
+   */
+  DeliverMin?: Amount
+}
+
+/**
+ * Verify the form and type of an CheckCash at runtime.
+ *
+ * @param tx - An CheckCash Transaction.
+ * @throws When the CheckCash is Malformed.
+ */
+export function validateCheckCash(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Amount == null && tx.DeliverMin == null) {
+    throw new ValidationError(
+      'CheckCash: must have either Amount or DeliverMin',
+    )
+  }
+
+  if (tx.Amount != null && tx.DeliverMin != null) {
+    throw new ValidationError(
+      'CheckCash: cannot have both Amount and DeliverMin',
+    )
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Necessary check
+  if (tx.Amount != null && tx.Amount !== undefined && !isAmount(tx.Amount)) {
+    throw new ValidationError('CheckCash: invalid Amount')
+  }
+
+  if (
+    tx.DeliverMin != null &&
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Necessary check
+    tx.DeliverMin !== undefined &&
+    !isAmount(tx.DeliverMin)
+  ) {
+    throw new ValidationError('CheckCash: invalid DeliverMin')
+  }
+
+  if (tx.CheckID !== undefined && typeof tx.CheckID !== 'string') {
+    throw new ValidationError('CheckCash: invalid CheckID')
+  }
+}

package/src/models/transactions/checkCreate.ts

@@ -0,0 +1,90 @@
+/* eslint-disable complexity -- Necessary for validateCheckCreate */
+import { ValidationError } from '../../errors'
+import { Amount } from '../common'
+
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  isIssuedCurrency,
+} from './common'
+
+/**
+ * Create a Check object in the ledger, which is a deferred payment that can be
+ * cashed by its intended destination. The sender of this transaction is the
+ * sender of the Check.
+ *
+ * @category Transaction Models
+ */
+export interface CheckCreate extends BaseTransaction {
+  TransactionType: 'CheckCreate'
+  /** The unique address of the account that can cash the Check. */
+  Destination: string
+  /**
+   * Maximum amount of source currency the Check is allowed to debit the
+   * sender, including transfer fees on non-XRP currencies. The Check can only
+   * credit the destination with the same currency (from the same issuer, for
+   * non-XRP currencies). For non-XRP amounts, the nested field names MUST be.
+   * lower-case.
+   */
+  SendMax: Amount
+  /**
+   * Arbitrary tag that identifies the reason for the Check, or a hosted.
+   * recipient to pay.
+   */
+  DestinationTag?: number
+  /**
+   * Time after which the Check is no longer valid, in seconds since the Ripple.
+   * Epoch.
+   */
+  Expiration?: number
+  /**
+   * Arbitrary 256-bit hash representing a specific reason or identifier for.
+   * this Check.
+   */
+  InvoiceID?: string
+}
+
+/**
+ * Verify the form and type of an CheckCreate at runtime.
+ *
+ * @param tx - An CheckCreate Transaction.
+ * @throws When the CheckCreate is Malformed.
+ */
+export function validateCheckCreate(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.SendMax === undefined) {
+    throw new ValidationError('CheckCreate: missing field SendMax')
+  }
+
+  if (tx.Destination === undefined) {
+    throw new ValidationError('CheckCreate: missing field Destination')
+  }
+
+  if (
+    typeof tx.SendMax !== 'string' &&
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
+    !isIssuedCurrency(tx.SendMax as Record<string, unknown>)
+  ) {
+    throw new ValidationError('CheckCreate: invalid SendMax')
+  }
+
+  if (typeof tx.Destination !== 'string') {
+    throw new ValidationError('CheckCreate: invalid Destination')
+  }
+
+  if (
+    tx.DestinationTag !== undefined &&
+    typeof tx.DestinationTag !== 'number'
+  ) {
+    throw new ValidationError('CheckCreate: invalid DestinationTag')
+  }
+
+  if (tx.Expiration !== undefined && typeof tx.Expiration !== 'number') {
+    throw new ValidationError('CheckCreate: invalid Expiration')
+  }
+
+  if (tx.InvoiceID !== undefined && typeof tx.InvoiceID !== 'string') {
+    throw new ValidationError('CheckCreate: invalid InvoiceID')
+  }
+}

package/src/models/transactions/clawback.ts

@@ -0,0 +1,49 @@
+import { ValidationError } from '../../errors'
+import { IssuedCurrencyAmount } from '../common'
+
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  isIssuedCurrency,
+} from './common'
+
+/**
+ * The Clawback transaction is used by the token issuer to claw back
+ * issued tokens from a holder.
+ */
+export interface Clawback extends BaseTransaction {
+  TransactionType: 'Clawback'
+  /**
+   * Indicates the AccountID that submitted this transaction. The account MUST
+   * be the issuer of the currency.
+   */
+  Account: string
+  /**
+   * The amount of currency to deliver, and it must be non-XRP. The nested field
+   * names MUST be lower-case. The `issuer` field MUST be the holder's address,
+   * whom to be clawed back.
+   */
+  Amount: IssuedCurrencyAmount
+}
+
+/**
+ * Verify the form and type of an Clawback at runtime.
+ *
+ * @param tx - An Clawback Transaction.
+ * @throws When the Clawback is Malformed.
+ */
+export function validateClawback(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Amount == null) {
+    throw new ValidationError('Clawback: missing field Amount')
+  }
+
+  if (!isIssuedCurrency(tx.Amount)) {
+    throw new ValidationError('Clawback: invalid Amount')
+  }
+
+  if (isIssuedCurrency(tx.Amount) && tx.Account === tx.Amount.issuer) {
+    throw new ValidationError('Clawback: invalid holder Account')
+  }
+}