xrpl 4.1.0 → 4.2.0

package/src/models/methods/simulate.ts

@@ -0,0 +1,88 @@
+import {
+  BaseTransaction,
+  Transaction,
+  TransactionMetadata,
+} from '../transactions'
+
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The `simulate` method simulates a transaction without submitting it to the network.
+ * Returns a {@link SimulateResponse}.
+ *
+ * @category Requests
+ */
+export type SimulateRequest = BaseRequest & {
+  command: 'simulate'
+
+  binary?: boolean
+} & (
+    | {
+        tx_blob: string
+        tx_json?: never
+      }
+    | {
+        tx_json: Transaction
+        tx_blob?: never
+      }
+  )
+
+export type SimulateBinaryRequest = SimulateRequest & {
+  binary: true
+}
+
+export type SimulateJsonRequest = SimulateRequest & {
+  binary?: false
+}
+
+/**
+ * Response expected from an {@link SimulateRequest}.
+ *
+ * @category Responses
+ */
+export type SimulateResponse = SimulateJsonResponse | SimulateBinaryResponse
+
+export interface SimulateBinaryResponse extends BaseResponse {
+  result: {
+    applied: false
+
+    engine_result: string
+
+    engine_result_code: number
+
+    engine_result_message: string
+
+    tx_blob: string
+
+    meta_blob: string
+
+    /**
+     * The ledger index of the ledger version that was used to generate this
+     * response.
+     */
+    ledger_index: number
+  }
+}
+
+export interface SimulateJsonResponse<T extends BaseTransaction = Transaction>
+  extends BaseResponse {
+  result: {
+    applied: false
+
+    engine_result: string
+
+    engine_result_code: number
+
+    engine_result_message: string
+
+    /**
+     * The ledger index of the ledger version that was used to generate this
+     * response.
+     */
+    ledger_index: number
+
+    tx_json: T
+
+    meta?: TransactionMetadata<T>
+  }
+}

package/src/models/transactions/AMMClawback.ts

@@ -0,0 +1,120 @@
+import { ValidationError } from '../../errors'
+import { Currency, IssuedCurrency, IssuedCurrencyAmount } from '../common'
+
+import {
+  Account,
+  BaseTransaction,
+  GlobalFlags,
+  isAccount,
+  isAmount,
+  isCurrency,
+  validateBaseTransaction,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
+
+/**
+ * Enum representing values for AMMClawback Transaction Flags.
+ *
+ * @category Transaction Flags
+ */
+export enum AMMClawbackFlags {
+  tfClawTwoAssets = 0x00000001,
+}
+
+/**
+ * Map of flags to boolean values representing {@link AMMClawback} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface AMMClawbackFlagsInterface extends GlobalFlags {
+  tfClawTwoAssets?: boolean
+}
+
+/**
+ * Claw back tokens from a holder that has deposited your issued tokens into an AMM pool.
+ *
+ * Clawback is disabled by default. To use clawback, you must send an AccountSet transaction to enable the
+ * Allow Trust Line Clawback setting. An issuer with any existing tokens cannot enable clawback. You can
+ * only enable Allow Trust Line Clawback if you have a completely empty owner directory, meaning you must
+ * do so before you set up any trust lines, offers, escrows, payment channels, checks, or signer lists.
+ * After you enable clawback, it cannot reverted: the account permanently gains the ability to claw back
+ * issued assets on trust lines.
+ */
+export interface AMMClawback extends BaseTransaction {
+  TransactionType: 'AMMClawback'
+
+  /**
+   * The account holding the asset to be clawed back.
+   */
+  Holder: Account
+
+  /**
+   * Specifies the asset that the issuer wants to claw back from the AMM pool.
+   * In JSON, this is an object with currency and issuer fields. The issuer field must match with Account.
+   */
+  Asset: IssuedCurrency
+
+  /**
+   * Specifies the other asset in the AMM's pool. In JSON, this is an object with currency and
+   * issuer fields (omit issuer for XRP).
+   */
+  Asset2: Currency
+
+  /**
+   * The maximum amount to claw back from the AMM account. The currency and issuer subfields should match
+   * the Asset subfields. If this field isn't specified, or the value subfield exceeds the holder's available
+   * tokens in the AMM, all of the holder's tokens will be clawed back.
+   */
+  Amount?: IssuedCurrencyAmount
+}
+
+/**
+ * Verify the form and type of an AMMClawback at runtime.
+ *
+ * @param tx - An AMMClawback Transaction.
+ * @throws {ValidationError} When the transaction is malformed.
+ */
+export function validateAMMClawback(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'Holder', isAccount)
+
+  validateRequiredField(tx, 'Asset', isCurrency)
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- required
+  const asset = tx.Asset as IssuedCurrency
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- required
+  const amount = tx.Amount as IssuedCurrencyAmount
+
+  if (tx.Holder === asset.issuer) {
+    throw new ValidationError(
+      'AMMClawback: Holder and Asset.issuer must be distinct',
+    )
+  }
+
+  if (tx.Account !== asset.issuer) {
+    throw new ValidationError(
+      'AMMClawback: Account must be the same as Asset.issuer',
+    )
+  }
+
+  validateRequiredField(tx, 'Asset2', isCurrency)
+
+  validateOptionalField(tx, 'Amount', isAmount)
+
+  if (tx.Amount != null) {
+    if (amount.currency !== asset.currency) {
+      throw new ValidationError(
+        'AMMClawback: Amount.currency must match Asset.currency',
+      )
+    }
+
+    if (amount.issuer !== asset.issuer) {
+      throw new ValidationError(
+        'AMMClawback: Amount.issuer must match Amount.issuer',
+      )
+    }
+  }
+}

package/src/models/transactions/NFTokenMint.ts

@@ -38,6 +38,10 @@ export enum NFTokenMintFlags {
    * issuer.
    */
   tfTransferable = 0x00000008,
+  /**
+   * If set, indicates that this NFT's URI can be modified.
+   */
+  tfMutable = 0x00000010,
 }
 
 /**
@@ -51,6 +55,7 @@ export interface NFTokenMintFlagsInterface extends GlobalFlags {
   tfOnlyXRP?: boolean
   tfTrustLine?: boolean
   tfTransferable?: boolean
+  tfMutable?: boolean
 }
 
 /**

package/src/models/transactions/NFTokenModify.ts

@@ -0,0 +1,67 @@
+import { ValidationError } from '../../errors'
+import { isHex } from '../utils'
+
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  isAccount,
+  isString,
+  validateOptionalField,
+  Account,
+  validateRequiredField,
+} from './common'
+
+/**
+ * The NFTokenModify transaction modifies an NFToken's URI
+ * if its tfMutable is set to true.
+ */
+export interface NFTokenModify extends BaseTransaction {
+  TransactionType: 'NFTokenModify'
+  /**
+   * Identifies the NFTokenID of the NFToken object that the
+   * offer references.
+   */
+  NFTokenID: string
+  /**
+   * Indicates the AccountID of the account that owns the corresponding NFToken.
+   * Can be omitted if the owner is the account submitting this transaction
+   */
+  Owner?: Account
+  /**
+   * URI that points to the data and/or metadata associated with the NFT.
+   * This field need not be an HTTP or HTTPS URL; it could be an IPFS URI, a
+   * magnet link, immediate data encoded as an RFC2379 "data" URL, or even an
+   * opaque issuer-specific encoding. The URI is NOT checked for validity, but
+   * the field is limited to a maximum length of 256 bytes.
+   *
+   * This field must be hex-encoded. You can use `convertStringToHex` to
+   * convert this field to the proper encoding.
+   *
+   * This field must not be an empty string. Omit it from the transaction or
+   * set to `null` if you do not use it.
+   */
+  URI?: string | null
+}
+
+/**
+ * Verify the form and type of an NFTokenModify at runtime.
+ *
+ * @param tx - An NFTokenModify Transaction.
+ * @throws When the NFTokenModify is Malformed.
+ */
+export function validateNFTokenModify(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'NFTokenID', isString)
+  validateOptionalField(tx, 'Owner', isAccount)
+  validateOptionalField(tx, 'URI', isString)
+
+  if (tx.URI !== undefined && typeof tx.URI === 'string') {
+    if (tx.URI === '') {
+      throw new ValidationError('NFTokenModify: URI must not be empty string')
+    }
+    if (!isHex(tx.URI)) {
+      throw new ValidationError('NFTokenModify: URI must be in hex format')
+    }
+  }
+}

package/src/models/transactions/accountDelete.ts

@@ -7,6 +7,7 @@ import {
   validateCredentialsList,
   validateOptionalField,
   validateRequiredField,
+  MAX_AUTHORIZED_CREDENTIALS,
 } from './common'
 
 /**
@@ -54,5 +55,6 @@ export function validateAccountDelete(tx: Record<string, unknown>): void {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- known from base check
     tx.TransactionType as string,
     true,
+    MAX_AUTHORIZED_CREDENTIALS,
   )
 }

package/src/models/transactions/common.ts

@@ -9,15 +9,15 @@ import {
   AuthorizeCredential,
   Currency,
   IssuedCurrencyAmount,
+  MPTAmount,
   Memo,
   Signer,
   XChainBridge,
-  MPTAmount,
 } from '../common'
 import { onlyHasFields } from '../utils'
 
 const MEMO_SIZE = 3
-const MAX_CREDENTIALS_LIST_LENGTH = 8
+export const MAX_AUTHORIZED_CREDENTIALS = 8
 const MAX_CREDENTIAL_BYTE_LENGTH = 64
 const MAX_CREDENTIAL_TYPE_LENGTH = MAX_CREDENTIAL_BYTE_LENGTH * 2
 
@@ -134,7 +134,9 @@ export function isIssuedCurrency(
  * @param input - The input to check the form and type of
  * @returns Whether the AuthorizeCredential is properly formed
  */
-function isAuthorizeCredential(input: unknown): input is AuthorizeCredential {
+export function isAuthorizeCredential(
+  input: unknown,
+): input is AuthorizeCredential {
   return (
     isRecord(input) &&
     isRecord(input.Credential) &&
@@ -455,13 +457,16 @@ export function validateCredentialType(tx: Record<string, unknown>): void {
  * @param credentials An array of credential IDs to check for errors
  * @param transactionType The transaction type to include in error messages
  * @param isStringID Toggle for if array contains IDs instead of AuthorizeCredential objects
+ * @param maxCredentials The maximum length of the credentials array.
+ *        PermissionedDomainSet transaction uses 10, other transactions use 8.
  * @throws Validation Error if the formatting is incorrect
  */
-// eslint-disable-next-line max-lines-per-function -- separating logic further will add unnecessary complexity
+// eslint-disable-next-line max-lines-per-function, max-params -- separating logic further will add unnecessary complexity
 export function validateCredentialsList(
   credentials: unknown,
   transactionType: string,
   isStringID: boolean,
+  maxCredentials: number,
 ): void {
   if (credentials == null) {
     return
@@ -471,9 +476,9 @@ export function validateCredentialsList(
       `${transactionType}: Credentials must be an array`,
     )
   }
-  if (credentials.length > MAX_CREDENTIALS_LIST_LENGTH) {
+  if (credentials.length > maxCredentials) {
     throw new ValidationError(
-      `${transactionType}: Credentials length cannot exceed ${MAX_CREDENTIALS_LIST_LENGTH} elements`,
+      `${transactionType}: Credentials length cannot exceed ${maxCredentials} elements`,
     )
   } else if (credentials.length === 0) {
     throw new ValidationError(
@@ -500,7 +505,42 @@ export function validateCredentialsList(
   }
 }
 
-function containsDuplicates(objectList: object[]): boolean {
-  const objSet = new Set(objectList.map((obj) => JSON.stringify(obj)))
-  return objSet.size !== objectList.length
+// Type guard to ensure we're working with AuthorizeCredential[]
+// Note: This is not a rigorous type-guard. A more thorough solution would be to iterate over the array and check each item.
+function isAuthorizeCredentialArray(
+  list: AuthorizeCredential[] | string[],
+): list is AuthorizeCredential[] {
+  return typeof list[0] !== 'string'
+}
+
+/**
+ * Check if an array of objects contains any duplicates.
+ *
+ * @param objectList - Array of objects to check for duplicates
+ * @returns True if duplicates exist, false otherwise
+ */
+export function containsDuplicates(
+  objectList: AuthorizeCredential[] | string[],
+): boolean {
+  // Case-1: Process a list of string-IDs
+  if (typeof objectList[0] === 'string') {
+    const objSet = new Set(objectList.map((obj) => JSON.stringify(obj)))
+    return objSet.size !== objectList.length
+  }
+
+  // Case-2: Process a list of nested objects
+  const seen = new Set<string>()
+
+  if (isAuthorizeCredentialArray(objectList)) {
+    for (const item of objectList) {
+      const key = `${item.Credential.Issuer}-${item.Credential.CredentialType}`
+      // eslint-disable-next-line max-depth -- necessary to check for type-guards
+      if (seen.has(key)) {
+        return true
+      }
+      seen.add(key)
+    }
+  }
+
+  return false
 }

package/src/models/transactions/depositPreauth.ts

@@ -5,6 +5,7 @@ import {
   BaseTransaction,
   validateBaseTransaction,
   validateCredentialsList,
+  MAX_AUTHORIZED_CREDENTIALS,
 } from './common'
 
 /**
@@ -72,6 +73,7 @@ export function validateDepositPreauth(tx: Record<string, unknown>): void {
       // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- confirmed in base transaction check
       tx.TransactionType as string,
       false,
+      MAX_AUTHORIZED_CREDENTIALS,
     )
   } else if (tx.UnauthorizeCredentials !== undefined) {
     validateCredentialsList(
@@ -79,6 +81,7 @@ export function validateDepositPreauth(tx: Record<string, unknown>): void {
       // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- confirmed in base transaction check
       tx.TransactionType as string,
       false,
+      MAX_AUTHORIZED_CREDENTIALS,
     )
   }
 }

package/src/models/transactions/escrowFinish.ts

@@ -7,6 +7,7 @@ import {
   validateBaseTransaction,
   validateCredentialsList,
   validateRequiredField,
+  MAX_AUTHORIZED_CREDENTIALS,
 } from './common'
 
 /**
@@ -55,6 +56,7 @@ export function validateEscrowFinish(tx: Record<string, unknown>): void {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- known from base check
     tx.TransactionType as string,
     true,
+    MAX_AUTHORIZED_CREDENTIALS,
   )
 
   if (tx.OfferSequence == null) {

package/src/models/transactions/index.ts

@@ -15,13 +15,18 @@ export {
 } from './accountSet'
 export { AccountDelete } from './accountDelete'
 export { AMMBid } from './AMMBid'
+export {
+  AMMClawbackFlags,
+  AMMClawbackFlagsInterface,
+  AMMClawback,
+} from './AMMClawback'
+export { AMMCreate } from './AMMCreate'
 export { AMMDelete } from './AMMDelete'
 export {
   AMMDepositFlags,
   AMMDepositFlagsInterface,
   AMMDeposit,
 } from './AMMDeposit'
-export { AMMCreate } from './AMMCreate'
 export { AMMVote } from './AMMVote'
 export {
   AMMWithdrawFlags,
@@ -71,6 +76,7 @@ export {
   NFTokenMintFlags,
   NFTokenMintFlagsInterface,
 } from './NFTokenMint'
+export { NFTokenModify, validateNFTokenModify } from './NFTokenModify'
 export { OfferCancel } from './offerCancel'
 export {
   OfferCreateFlags,
@@ -105,3 +111,6 @@ export {
   XChainModifyBridgeFlags,
   XChainModifyBridgeFlagsInterface,
 } from './XChainModifyBridge'
+
+export { PermissionedDomainSet } from './permissionedDomainSet'
+export { PermissionedDomainDelete } from './permissionedDomainDelete'

package/src/models/transactions/payment.ts

@@ -13,6 +13,7 @@ import {
   isNumber,
   Account,
   validateCredentialsList,
+  MAX_AUTHORIZED_CREDENTIALS,
 } from './common'
 import type { TransactionMetadataBase } from './metadata'
 
@@ -188,6 +189,7 @@ export function validatePayment(tx: Record<string, unknown>): void {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- known from base check
     tx.TransactionType as string,
     true,
+    MAX_AUTHORIZED_CREDENTIALS,
   )
 
   if (tx.InvoiceID !== undefined && typeof tx.InvoiceID !== 'string') {

package/src/models/transactions/paymentChannelClaim.ts

@@ -5,6 +5,7 @@ import {
   GlobalFlags,
   validateBaseTransaction,
   validateCredentialsList,
+  MAX_AUTHORIZED_CREDENTIALS,
 } from './common'
 
 /**
@@ -153,6 +154,7 @@ export function validatePaymentChannelClaim(tx: Record<string, unknown>): void {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- known from base check
     tx.TransactionType as string,
     true,
+    MAX_AUTHORIZED_CREDENTIALS,
   )
 
   if (tx.Channel === undefined) {

package/src/models/transactions/permissionedDomainDelete.ts

@@ -0,0 +1,28 @@
+import {
+  BaseTransaction,
+  isString,
+  validateBaseTransaction,
+  validateRequiredField,
+} from './common'
+
+export interface PermissionedDomainDelete extends BaseTransaction {
+  /* The transaction type (PermissionedDomainDelete). */
+  TransactionType: 'PermissionedDomainDelete'
+
+  /* The domain to delete. */
+  DomainID: string
+}
+
+/**
+ * Verify the form and type of a PermissionedDomainDelete transaction.
+ *
+ * @param tx - The transaction to verify.
+ * @throws When the transaction is malformed.
+ */
+export function validatePermissionedDomainDelete(
+  tx: Record<string, unknown>,
+): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'DomainID', isString)
+}

package/src/models/transactions/permissionedDomainSet.ts

@@ -0,0 +1,54 @@
+import { AuthorizeCredential } from '../common'
+
+import {
+  BaseTransaction,
+  isString,
+  validateBaseTransaction,
+  validateOptionalField,
+  validateRequiredField,
+  validateCredentialsList,
+} from './common'
+
+const MAX_ACCEPTED_CREDENTIALS = 10
+
+export interface PermissionedDomainSet extends BaseTransaction {
+  /* The transaction type (PermissionedDomainSet). */
+  TransactionType: 'PermissionedDomainSet'
+
+  /* The domain to modify. Must be included if modifying an existing domain. */
+  DomainID?: string
+
+  /* The credentials that are accepted by the domain. Ownership of one
+  of these credentials automatically makes you a member of the domain.
+  An empty array means deleting the field. */
+  AcceptedCredentials: AuthorizeCredential[]
+}
+
+/**
+ * Validate a PermissionedDomainSet transaction.
+ *
+ * @param tx - The transaction to validate.
+ * @throws {ValidationError} When the transaction is invalid.
+ */
+export function validatePermissionedDomainSet(
+  tx: Record<string, unknown>,
+): void {
+  validateBaseTransaction(tx)
+
+  validateOptionalField(tx, 'DomainID', isString)
+  validateRequiredField(
+    tx,
+    'AcceptedCredentials',
+    () => tx.AcceptedCredentials instanceof Array,
+  )
+
+  validateCredentialsList(
+    tx.AcceptedCredentials,
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- known from base check
+    tx.TransactionType as string,
+    // PermissionedDomainSet uses AuthorizeCredential nested objects only, strings are not allowed
+    false,
+    // PermissionedDomainSet uses at most 10 accepted credentials. This is different from Credential-feature transactions.
+    MAX_ACCEPTED_CREDENTIALS,
+  )
+}