xrpl 4.0.1-mpt-beta → 4.2.0-batch.0

package/src/models/transactions/batch.ts

@@ -0,0 +1,147 @@
+import { ValidationError } from '../../errors'
+import { Signer } from '../common'
+
+import {
+  BaseTransaction,
+  GlobalFlagsInterface,
+  isArray,
+  isObject,
+  isString,
+  validateBaseTransaction,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
+import type { SubmittableTransaction } from './transaction'
+
+/**
+ * Enum representing values of {@link Batch} transaction flags.
+ *
+ * @category Transaction Flags
+ */
+export enum BatchFlags {
+  tfAllOrNothing = 0x00010000,
+  tfOnlyOne = 0x00020000,
+  tfUntilFailure = 0x00040000,
+  tfIndependent = 0x00080000,
+}
+
+/**
+ * Map of flags to boolean values representing {@link Batch} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface BatchFlagsInterface extends GlobalFlagsInterface {
+  tfAllOrNothing?: boolean
+  tfOnlyOne?: boolean
+  tfUntilFailure?: boolean
+  tfIndependent?: boolean
+}
+
+export type BatchInnerTransaction = SubmittableTransaction & {
+  Fee?: '0'
+
+  SigningPubKey?: ''
+
+  TxnSignature?: never
+
+  Signers?: never
+
+  LastLedgerSequence?: never
+}
+
+export interface BatchSigner {
+  BatchSigner: {
+    Account: string
+
+    SigningPubKey?: string
+
+    TxnSignature?: string
+
+    Signers?: Signer[]
+  }
+}
+
+/**
+ * @category Transaction Models
+ */
+export interface Batch extends BaseTransaction {
+  TransactionType: 'Batch'
+
+  BatchSigners?: BatchSigner[]
+
+  RawTransactions: Array<{
+    RawTransaction: BatchInnerTransaction
+  }>
+}
+
+/**
+ * Verify the form and type of a Batch at runtime.
+ *
+ * @param tx - A Batch Transaction.
+ * @throws When the Batch is malformed.
+ */
+// eslint-disable-next-line max-lines-per-function -- needed here due to the complexity
+export function validateBatch(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'RawTransactions', isArray)
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+  const rawTransactions = tx.RawTransactions as unknown[]
+  rawTransactions.forEach((rawTxObj, index) => {
+    if (!isObject(rawTxObj)) {
+      throw new ValidationError(
+        `Batch: RawTransactions[${index}] is not object.`,
+      )
+    }
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+    const rawTxRecord = rawTxObj as Record<string, unknown>
+    validateRequiredField(rawTxRecord, 'RawTransaction', isObject, {
+      paramName: `RawTransactions[${index}].RawTransaction`,
+      txType: 'Batch',
+    })
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+    const rawTx = rawTxRecord.RawTransaction as Record<string, unknown>
+    if (rawTx.TransactionType === 'Batch') {
+      throw new ValidationError(
+        `Batch: RawTransactions[${index}] is a Batch transaction. Cannot nest Batch transactions.`,
+      )
+    }
+  })
+  // Full validation of each `RawTransaction` object is done in `validate` to avoid dependency cycles
+
+  validateOptionalField(tx, 'BatchSigners', isArray)
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+  const batchSigners = tx.BatchSigners as unknown[] | undefined
+  batchSigners?.forEach((signerObj, index) => {
+    if (!isObject(signerObj)) {
+      throw new ValidationError(`Batch: BatchSigners[${index}] is not object.`)
+    }
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+    const signerRecord = signerObj as Record<string, unknown>
+    validateRequiredField(signerRecord, 'BatchSigner', isObject, {
+      paramName: `BatchSigners[${index}].BatchSigner`,
+      txType: 'Batch',
+    })
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+    const signer = signerRecord.BatchSigner as Record<string, unknown>
+    validateRequiredField(signer, 'Account', isString, {
+      paramName: `BatchSigners[${index}].Account`,
+      txType: 'Batch',
+    })
+    validateOptionalField(signer, 'SigningPubKey', isString, {
+      paramName: `BatchSigners[${index}].SigningPubKey`,
+      txType: 'Batch',
+    })
+    validateOptionalField(signer, 'TxnSignature', isString, {
+      paramName: `BatchSigners[${index}].TxnSignature`,
+      txType: 'Batch',
+    })
+    validateOptionalField(signer, 'Signers', isArray, {
+      paramName: `BatchSigners[${index}].Signers`,
+      txType: 'Batch',
+    })
+  })
+}

package/src/models/transactions/clawback.ts

@@ -31,7 +31,7 @@ export interface Clawback extends BaseTransaction {
    * Indicates the AccountID that the issuer wants to clawback. This field is only valid for clawing back
    * MPTs.
    */
-  MPTokenHolder?: string
+  Holder?: string
 }
 
 /**
@@ -42,7 +42,7 @@ export interface Clawback extends BaseTransaction {
  */
 export function validateClawback(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
-  validateOptionalField(tx, 'MPTokenHolder', isAccount)
+  validateOptionalField(tx, 'Holder', isAccount)
 
   if (tx.Amount == null) {
     throw new ValidationError('Clawback: missing field Amount')
@@ -56,17 +56,15 @@ export function validateClawback(tx: Record<string, unknown>): void {
     throw new ValidationError('Clawback: invalid holder Account')
   }
 
-  if (isMPTAmount(tx.Amount) && tx.Account === tx.MPTokenHolder) {
+  if (isMPTAmount(tx.Amount) && tx.Account === tx.Holder) {
     throw new ValidationError('Clawback: invalid holder Account')
   }
 
-  if (isIssuedCurrency(tx.Amount) && tx.MPTokenHolder) {
-    throw new ValidationError(
-      'Clawback: cannot have MPTokenHolder for currency',
-    )
+  if (isIssuedCurrency(tx.Amount) && tx.Holder) {
+    throw new ValidationError('Clawback: cannot have Holder for currency')
   }
 
-  if (isMPTAmount(tx.Amount) && !tx.MPTokenHolder) {
-    throw new ValidationError('Clawback: missing MPTokenHolder')
+  if (isMPTAmount(tx.Amount) && !tx.Holder) {
+    throw new ValidationError('Clawback: missing Holder')
   }
 }

package/src/models/transactions/common.ts

@@ -1,19 +1,25 @@
+/* eslint-disable max-lines -- common utility file */
+import { HEX_REGEX } from '@xrplf/isomorphic/utils'
 import { isValidClassicAddress, isValidXAddress } from 'ripple-address-codec'
 import { TRANSACTION_TYPES } from 'ripple-binary-codec'
 
 import { ValidationError } from '../../errors'
 import {
   Amount,
+  AuthorizeCredential,
   Currency,
   IssuedCurrencyAmount,
+  MPTAmount,
   Memo,
   Signer,
   XChainBridge,
-  MPTAmount,
 } from '../common'
 import { onlyHasFields } from '../utils'
 
 const MEMO_SIZE = 3
+export const MAX_AUTHORIZED_CREDENTIALS = 8
+const MAX_CREDENTIAL_BYTE_LENGTH = 64
+const MAX_CREDENTIAL_TYPE_LENGTH = MAX_CREDENTIAL_BYTE_LENGTH * 2
 
 function isMemo(obj: { Memo?: unknown }): boolean {
   if (obj.Memo == null) {
@@ -61,6 +67,7 @@ const ISSUE_SIZE = 2
 const ISSUED_CURRENCY_SIZE = 3
 const XCHAIN_BRIDGE_SIZE = 4
 const MPTOKEN_SIZE = 2
+const AUTHORIZE_CREDENTIAL_SIZE = 1
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object'
@@ -121,6 +128,24 @@ export function isIssuedCurrency(
   )
 }
 
+/**
+ * Verify the form and type of an AuthorizeCredential at runtime
+ *
+ * @param input - The input to check the form and type of
+ * @returns Whether the AuthorizeCredential is properly formed
+ */
+export function isAuthorizeCredential(
+  input: unknown,
+): input is AuthorizeCredential {
+  return (
+    isRecord(input) &&
+    isRecord(input.Credential) &&
+    Object.keys(input).length === AUTHORIZE_CREDENTIAL_SIZE &&
+    typeof input.Credential.CredentialType === 'string' &&
+    typeof input.Credential.Issuer === 'string'
+  )
+}
+
 /**
  * Verify the form and type of an MPT at runtime.
  *
@@ -185,31 +210,57 @@ export function isXChainBridge(input: unknown): input is XChainBridge {
   )
 }
 
+/**
+ * Verify the form and type of an Object at runtime.
+ *
+ * @param input - The object to check the form and type of.
+ * @returns Whether the Object is properly formed.
+ */
+export function isObject(input: unknown): input is object {
+  return typeof input === 'object'
+}
+
+/**
+ * Verify the form and type of an Array at runtime.
+ *
+ * @param input - The object to check the form and type of.
+ * @returns Whether the Array is properly formed.
+ */
+export function isArray(input: unknown): boolean {
+  return Array.isArray(input)
+}
+
 /* eslint-disable @typescript-eslint/restrict-template-expressions -- tx.TransactionType is checked before any calls */
 
 /**
  * Verify the form and type of a required type for a transaction at runtime.
  *
- * @param tx - The transaction input to check the form and type of.
- * @param paramName - The name of the transaction parameter.
+ * @param tx - The object input to check the form and type of.
+ * @param param - The object parameter.
  * @param checkValidity - The function to use to check the type.
+ * @param errorOpts - Extra values to make the error message easier to understand.
+ * @param errorOpts.txType - The transaction type throwing the error.
+ * @param errorOpts.paramName - The name of the parameter in the transaction with the error.
  * @throws
  */
+// eslint-disable-next-line max-params -- helper function
 export function validateRequiredField(
   tx: Record<string, unknown>,
-  paramName: string,
+  param: string,
   checkValidity: (inp: unknown) => boolean,
+  errorOpts: {
+    txType?: string
+    paramName?: string
+  } = {},
 ): void {
-  if (tx[paramName] == null) {
-    throw new ValidationError(
-      `${tx.TransactionType}: missing field ${paramName}`,
-    )
+  const paramNameStr = errorOpts.paramName ?? param
+  const txType = errorOpts.txType ?? tx.TransactionType
+  if (tx[param] == null) {
+    throw new ValidationError(`${txType}: missing field ${paramNameStr}`)
   }
 
-  if (!checkValidity(tx[paramName])) {
-    throw new ValidationError(
-      `${tx.TransactionType}: invalid field ${paramName}`,
-    )
+  if (!checkValidity(tx[param])) {
+    throw new ValidationError(`${txType}: invalid field ${paramNameStr}`)
   }
 }
 
@@ -217,26 +268,39 @@ export function validateRequiredField(
  * Verify the form and type of an optional type for a transaction at runtime.
  *
  * @param tx - The transaction input to check the form and type of.
- * @param paramName - The name of the transaction parameter.
+ * @param param - The object parameter.
  * @param checkValidity - The function to use to check the type.
+ * @param errorOpts - Extra values to make the error message easier to understand.
+ * @param errorOpts.txType - The transaction type throwing the error.
+ * @param errorOpts.paramName - The name of the parameter in the transaction with the error.
  * @throws
  */
+// eslint-disable-next-line max-params -- helper function
 export function validateOptionalField(
   tx: Record<string, unknown>,
-  paramName: string,
+  param: string,
   checkValidity: (inp: unknown) => boolean,
+  errorOpts: {
+    txType?: string
+    paramName?: string
+  } = {},
 ): void {
-  if (tx[paramName] !== undefined && !checkValidity(tx[paramName])) {
-    throw new ValidationError(
-      `${tx.TransactionType}: invalid field ${paramName}`,
-    )
+  const paramNameStr = errorOpts.paramName ?? param
+  const txType = errorOpts.txType ?? tx.TransactionType
+  if (tx[param] !== undefined && !checkValidity(tx[param])) {
+    throw new ValidationError(`${txType}: invalid field ${paramNameStr}`)
   }
 }
 
 /* eslint-enable @typescript-eslint/restrict-template-expressions -- checked before */
 
-// eslint-disable-next-line @typescript-eslint/no-empty-interface -- no global flags right now, so this is fine
-export interface GlobalFlags {}
+export enum GlobalFlags {
+  tfInnerBatchTxn = 0x40000000,
+}
+
+export interface GlobalFlagsInterface {
+  tfInnerBatchTxn?: boolean
+}
 
 /**
  * Every transaction has the same set of common fields.
@@ -269,7 +333,7 @@ export interface BaseTransaction {
    */
   AccountTxnID?: string
   /** Set of bit-flags for this transaction. */
-  Flags?: number | GlobalFlags
+  Flags?: number | GlobalFlagsInterface
   /**
    * Highest ledger index this transaction can appear in. Specifying this field
    * places a strict upper limit on how long the transaction can wait to be
@@ -332,7 +396,9 @@ export function validateBaseTransaction(common: Record<string, unknown>): void {
   }
 
   if (!TRANSACTION_TYPES.includes(common.TransactionType)) {
-    throw new ValidationError('BaseTransaction: Unknown TransactionType')
+    throw new ValidationError(
+      `BaseTransaction: Unknown TransactionType ${common.TransactionType}`,
+    )
   }
 
   validateRequiredField(common, 'Account', isString)
@@ -387,3 +453,134 @@ export function parseAmountValue(amount: unknown): number {
   }
   return parseFloat(amount.value)
 }
+
+/**
+ * Verify the form and type of a CredentialType at runtime.
+ *
+ * @param tx A CredentialType Transaction.
+ * @throws when the CredentialType is malformed.
+ */
+export function validateCredentialType(tx: Record<string, unknown>): void {
+  if (typeof tx.TransactionType !== 'string') {
+    throw new ValidationError('Invalid TransactionType')
+  }
+  if (tx.CredentialType === undefined) {
+    throw new ValidationError(
+      `${tx.TransactionType}: missing field CredentialType`,
+    )
+  }
+
+  if (!isString(tx.CredentialType)) {
+    throw new ValidationError(
+      `${tx.TransactionType}: CredentialType must be a string`,
+    )
+  }
+  if (tx.CredentialType.length === 0) {
+    throw new ValidationError(
+      `${tx.TransactionType}: CredentialType cannot be an empty string`,
+    )
+  } else if (tx.CredentialType.length > MAX_CREDENTIAL_TYPE_LENGTH) {
+    throw new ValidationError(
+      `${tx.TransactionType}: CredentialType length cannot be > ${MAX_CREDENTIAL_TYPE_LENGTH}`,
+    )
+  }
+
+  if (!HEX_REGEX.test(tx.CredentialType)) {
+    throw new ValidationError(
+      `${tx.TransactionType}: CredentialType must be encoded in hex`,
+    )
+  }
+}
+
+/**
+ * Check a CredentialAuthorize array for parameter errors
+ *
+ * @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, 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
+  }
+  if (!Array.isArray(credentials)) {
+    throw new ValidationError(
+      `${transactionType}: Credentials must be an array`,
+    )
+  }
+  if (credentials.length > maxCredentials) {
+    throw new ValidationError(
+      `${transactionType}: Credentials length cannot exceed ${maxCredentials} elements`,
+    )
+  } else if (credentials.length === 0) {
+    throw new ValidationError(
+      `${transactionType}: Credentials cannot be an empty array`,
+    )
+  }
+  credentials.forEach((credential) => {
+    if (isStringID) {
+      if (!isString(credential)) {
+        throw new ValidationError(
+          `${transactionType}: Invalid Credentials ID list format`,
+        )
+      }
+    } else if (!isAuthorizeCredential(credential)) {
+      throw new ValidationError(
+        `${transactionType}: Invalid Credentials format`,
+      )
+    }
+  })
+  if (containsDuplicates(credentials)) {
+    throw new ValidationError(
+      `${transactionType}: Credentials cannot contain duplicate elements`,
+    )
+  }
+}
+
+// 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}`
+      if (seen.has(key)) {
+        return true
+      }
+      seen.add(key)
+    }
+  }
+
+  return false
+}

package/src/models/transactions/depositPreauth.ts

@@ -1,6 +1,12 @@
 import { ValidationError } from '../../errors'
+import { AuthorizeCredential } from '../common'
 
-import { BaseTransaction, validateBaseTransaction } from './common'
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  validateCredentialsList,
+  MAX_AUTHORIZED_CREDENTIALS,
+} from './common'
 
 /**
  * A DepositPreauth transaction gives another account pre-approval to deliver
@@ -18,6 +24,16 @@ export interface DepositPreauth extends BaseTransaction {
    * revoked.
    */
   Unauthorize?: string
+
+  /**
+   * The credential(s) to preauthorize.
+   */
+  AuthorizeCredentials?: AuthorizeCredential[]
+
+  /**
+   * The credential(s) whose preauthorization should be revoked.
+   */
+  UnauthorizeCredentials?: AuthorizeCredential[]
 }
 
 /**
@@ -29,17 +45,7 @@ export interface DepositPreauth extends BaseTransaction {
 export function validateDepositPreauth(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
 
-  if (tx.Authorize !== undefined && tx.Unauthorize !== undefined) {
-    throw new ValidationError(
-      "DepositPreauth: can't provide both Authorize and Unauthorize fields",
-    )
-  }
-
-  if (tx.Authorize === undefined && tx.Unauthorize === undefined) {
-    throw new ValidationError(
-      'DepositPreauth: must provide either Authorize or Unauthorize field',
-    )
-  }
+  validateSingleAuthorizationFieldProvided(tx)
 
   if (tx.Authorize !== undefined) {
     if (typeof tx.Authorize !== 'string') {
@@ -51,9 +57,7 @@ export function validateDepositPreauth(tx: Record<string, unknown>): void {
         "DepositPreauth: Account can't preauthorize its own address",
       )
     }
-  }
-
-  if (tx.Unauthorize !== undefined) {
+  } else if (tx.Unauthorize !== undefined) {
     if (typeof tx.Unauthorize !== 'string') {
       throw new ValidationError('DepositPreauth: Unauthorize must be a string')
     }
@@ -63,5 +67,40 @@ export function validateDepositPreauth(tx: Record<string, unknown>): void {
         "DepositPreauth: Account can't unauthorize its own address",
       )
     }
+  } else if (tx.AuthorizeCredentials !== undefined) {
+    validateCredentialsList(
+      tx.AuthorizeCredentials,
+      // 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(
+      tx.UnauthorizeCredentials,
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- confirmed in base transaction check
+      tx.TransactionType as string,
+      false,
+      MAX_AUTHORIZED_CREDENTIALS,
+    )
+  }
+}
+
+// Boolean logic to ensure exactly one of 4 inputs was provided
+function validateSingleAuthorizationFieldProvided(
+  tx: Record<string, unknown>,
+): void {
+  const fields = [
+    'Authorize',
+    'Unauthorize',
+    'AuthorizeCredentials',
+    'UnauthorizeCredentials',
+  ]
+  const countProvided = fields.filter((key) => tx[key] !== undefined).length
+
+  if (countProvided !== 1) {
+    throw new ValidationError(
+      'DepositPreauth: Requires exactly one field of the following: Authorize, Unauthorize, AuthorizeCredentials, UnauthorizeCredentials.',
+    )
   }
 }

package/src/models/transactions/escrowFinish.ts

@@ -5,7 +5,9 @@ import {
   BaseTransaction,
   isAccount,
   validateBaseTransaction,
+  validateCredentialsList,
   validateRequiredField,
+  MAX_AUTHORIZED_CREDENTIALS,
 } from './common'
 
 /**
@@ -32,6 +34,10 @@ export interface EscrowFinish extends BaseTransaction {
    * the held payment's Condition.
    */
   Fulfillment?: string
+  /** Credentials associated with the sender of this transaction.
+   * The credentials included must not be expired.
+   */
+  CredentialIDs?: string[]
 }
 
 /**
@@ -45,6 +51,14 @@ export function validateEscrowFinish(tx: Record<string, unknown>): void {
 
   validateRequiredField(tx, 'Owner', isAccount)
 
+  validateCredentialsList(
+    tx.CredentialIDs,
+    // 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) {
     throw new ValidationError('EscrowFinish: missing field OfferSequence')
   }