xrpl 4.3.0-smartescrow.3 → 4.4.0-smartescrow.0

package/src/models/transactions/clawback.ts

@@ -1,13 +1,15 @@
 import { ValidationError } from '../../errors'
-import { IssuedCurrencyAmount, MPTAmount } from '../common'
+import { ClawbackAmount } from '../common'
 
 import {
   BaseTransaction,
   validateBaseTransaction,
-  isIssuedCurrency,
+  isIssuedCurrencyAmount,
   isMPTAmount,
   isAccount,
   validateOptionalField,
+  isClawbackAmount,
+  validateRequiredField,
 } from './common'
 
 /**
@@ -26,7 +28,7 @@ export interface Clawback extends BaseTransaction {
    * names MUST be lower-case. If the amount is IOU, the `issuer` field MUST be the holder's address,
    * whom to be clawed back.
    */
-  Amount: IssuedCurrencyAmount | MPTAmount
+  Amount: ClawbackAmount
   /**
    * Indicates the AccountID that the issuer wants to clawback. This field is only valid for clawing back
    * MPTs.
@@ -42,17 +44,14 @@ export interface Clawback extends BaseTransaction {
  */
 export function validateClawback(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
+  validateRequiredField(tx, 'Amount', isClawbackAmount)
   validateOptionalField(tx, 'Holder', isAccount)
 
-  if (tx.Amount == null) {
-    throw new ValidationError('Clawback: missing field Amount')
-  }
-
-  if (!isIssuedCurrency(tx.Amount) && !isMPTAmount(tx.Amount)) {
+  if (!isIssuedCurrencyAmount(tx.Amount) && !isMPTAmount(tx.Amount)) {
     throw new ValidationError('Clawback: invalid Amount')
   }
 
-  if (isIssuedCurrency(tx.Amount) && tx.Account === tx.Amount.issuer) {
+  if (isIssuedCurrencyAmount(tx.Amount) && tx.Account === tx.Amount.issuer) {
     throw new ValidationError('Clawback: invalid holder Account')
   }
 
@@ -60,7 +59,7 @@ export function validateClawback(tx: Record<string, unknown>): void {
     throw new ValidationError('Clawback: invalid holder Account')
   }
 
-  if (isIssuedCurrency(tx.Amount) && tx.Holder) {
+  if (isIssuedCurrencyAmount(tx.Amount) && tx.Holder) {
     throw new ValidationError('Clawback: cannot have Holder for currency')
   }
 

package/src/models/transactions/common.ts

@@ -7,31 +7,42 @@ import { ValidationError } from '../../errors'
 import {
   Amount,
   AuthorizeCredential,
+  ClawbackAmount,
   Currency,
+  IssuedCurrency,
   IssuedCurrencyAmount,
   MPTAmount,
   Memo,
   Signer,
   XChainBridge,
 } from '../common'
-import { onlyHasFields } from '../utils'
+import { isHex, 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) {
+// Used for Vault transactions
+export const VAULT_DATA_MAX_BYTE_LENGTH = 256
+
+function isMemo(obj: unknown): obj is Memo {
+  if (!isRecord(obj)) {
+    return false
+  }
+
+  const memo = obj.Memo
+  if (!isRecord(memo)) {
     return false
   }
-  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
-  const memo = obj.Memo as Record<string, unknown>
   const size = Object.keys(memo).length
-  const validData = memo.MemoData == null || typeof memo.MemoData === 'string'
+  const validData =
+    memo.MemoData == null || (isString(memo.MemoData) && isHex(memo.MemoData))
   const validFormat =
-    memo.MemoFormat == null || typeof memo.MemoFormat === 'string'
-  const validType = memo.MemoType == null || typeof memo.MemoType === 'string'
+    memo.MemoFormat == null ||
+    (isString(memo.MemoFormat) && isHex(memo.MemoFormat))
+  const validType =
+    memo.MemoType == null || (isString(memo.MemoType) && isHex(memo.MemoType))
 
   return (
     size >= 1 &&
@@ -45,20 +56,21 @@ function isMemo(obj: { Memo?: unknown }): boolean {
 
 const SIGNER_SIZE = 3
 
-function isSigner(obj: unknown): boolean {
-  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
-  const signerWrapper = obj as Record<string, unknown>
+function isSigner(obj: unknown): obj is Signer {
+  if (!isRecord(obj)) {
+    return false
+  }
 
-  if (signerWrapper.Signer == null) {
+  const signer = obj.Signer
+  if (!isRecord(signer)) {
     return false
   }
-  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS and Signer is previously unknown
-  const signer = signerWrapper.Signer as Record<string, unknown>
+
   return (
     Object.keys(signer).length === SIGNER_SIZE &&
-    typeof signer.Account === 'string' &&
-    typeof signer.TxnSignature === 'string' &&
-    typeof signer.SigningPubKey === 'string'
+    isString(signer.Account) &&
+    isString(signer.TxnSignature) &&
+    isString(signer.SigningPubKey)
   )
 }
 
@@ -69,8 +81,14 @@ 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'
+/**
+ * Verify the form and type of a Record/Object at runtime.
+ *
+ * @param value - The object to check the form and type of.
+ * @returns Whether the Record/Object is properly formed.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
 
 /**
@@ -93,18 +111,50 @@ export function isNumber(num: unknown): num is number {
   return typeof num === 'number'
 }
 
+/**
+ * Checks whether the given value is a valid XRPL number string.
+ * Accepts integer, decimal, or scientific notation strings.
+ *
+ * Examples of valid input:
+ *   - "123"
+ *   - "-987.654"
+ *   - "+3.14e10"
+ *   - "-7.2e-9"
+ *
+ * @param value - The value to check.
+ * @returns True if value is a string that matches the XRPL number format, false otherwise.
+ */
+export function isXRPLNumber(value: unknown): value is XRPLNumber {
+  // Matches optional sign, digits, optional decimal, optional exponent (scientific)
+  // Allows leading zeros, but not empty string, lone sign, or missing digits
+  return (
+    typeof value === 'string' &&
+    /^[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?$/u.test(value.trim())
+  )
+}
+
+/**
+ * Verify the form and type of a Currency at runtime.
+ *
+ * @param input - The input to check the form and type of.
+ * @returns Whether the Currency is properly formed.
+ */
+export function isCurrency(input: unknown): input is Currency {
+  return isString(input) || isIssuedCurrency(input)
+}
+
 /**
  * Verify the form and type of an IssuedCurrency at runtime.
  *
  * @param input - The input to check the form and type of.
  * @returns Whether the IssuedCurrency is properly formed.
  */
-export function isCurrency(input: unknown): input is Currency {
+export function isIssuedCurrency(input: unknown): input is IssuedCurrency {
   return (
     isRecord(input) &&
     ((Object.keys(input).length === ISSUE_SIZE &&
-      typeof input.issuer === 'string' &&
-      typeof input.currency === 'string') ||
+      isString(input.issuer) &&
+      isString(input.currency)) ||
       (Object.keys(input).length === XRP_CURRENCY_SIZE &&
         input.currency === 'XRP'))
   )
@@ -116,15 +166,15 @@ export function isCurrency(input: unknown): input is Currency {
  * @param input - The input to check the form and type of.
  * @returns Whether the IssuedCurrencyAmount is properly formed.
  */
-export function isIssuedCurrency(
+export function isIssuedCurrencyAmount(
   input: unknown,
 ): input is IssuedCurrencyAmount {
   return (
     isRecord(input) &&
     Object.keys(input).length === ISSUED_CURRENCY_SIZE &&
-    typeof input.value === 'string' &&
-    typeof input.issuer === 'string' &&
-    typeof input.currency === 'string'
+    isString(input.value) &&
+    isString(input.issuer) &&
+    isString(input.currency)
   )
 }
 
@@ -161,11 +211,33 @@ export function isMPTAmount(input: unknown): input is MPTAmount {
   )
 }
 
+/**
+ * Type guard to verify if the input is a valid ClawbackAmount.
+ *
+ * A ClawbackAmount can be either an {@link IssuedCurrencyAmount} or an {@link MPTAmount}.
+ * This function checks if the input matches either type.
+ *
+ * @param input - The value to check for ClawbackAmount structure.
+ * @returns True if the input is an IssuedCurrencyAmount or MPTAmount, otherwise false.
+ */
+export function isClawbackAmount(input: unknown): input is ClawbackAmount {
+  return isIssuedCurrencyAmount(input) || isMPTAmount(input)
+}
+
 /**
  * Must be a valid account address
  */
 export type Account = string
 
+/**
+ * XRPL Number type represented as a string.
+ *
+ * This string can be an integer (e.g., "123"), a decimal (e.g., "123.45"),
+ * or in scientific notation (e.g., "1.23e5", "-4.56e-7").
+ * Used for fields that accept arbitrary-precision numbers in XRPL transactions and ledger objects.
+ */
+export type XRPLNumber = string
+
 /**
  * Verify a string is in fact a valid account address.
  *
@@ -188,7 +260,7 @@ export function isAccount(account: unknown): account is Account {
 export function isAmount(amount: unknown): amount is Amount {
   return (
     typeof amount === 'string' ||
-    isIssuedCurrency(amount) ||
+    isIssuedCurrencyAmount(amount) ||
     isMPTAmount(amount)
   )
 }
@@ -204,36 +276,60 @@ export function isXChainBridge(input: unknown): input is XChainBridge {
     isRecord(input) &&
     Object.keys(input).length === XCHAIN_BRIDGE_SIZE &&
     typeof input.LockingChainDoor === 'string' &&
-    isCurrency(input.LockingChainIssue) &&
+    isIssuedCurrency(input.LockingChainIssue) &&
     typeof input.IssuingChainDoor === 'string' &&
-    isCurrency(input.IssuingChainIssue)
+    isIssuedCurrency(input.IssuingChainIssue)
   )
 }
 
+/**
+ * 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<T = unknown>(input: unknown): input is T[] {
+  return input != null && 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.
- * @throws
+ * @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 ValidationError if the parameter is missing or invalid.
  */
-export function validateRequiredField(
-  tx: Record<string, unknown>,
-  paramName: string,
-  checkValidity: (inp: unknown) => boolean,
-): void {
-  if (tx[paramName] == null) {
+// eslint-disable-next-line max-params -- helper function
+export function validateRequiredField<
+  T extends Record<string, unknown>,
+  K extends keyof T,
+  V,
+>(
+  tx: T,
+  param: K,
+  checkValidity: (inp: unknown) => inp is V,
+  errorOpts: {
+    txType?: string
+    paramName?: string
+  } = {},
+): asserts tx is T & { [P in K]: V } {
+  const paramNameStr = errorOpts.paramName ?? param
+  const txType = errorOpts.txType ?? tx.TransactionType
+  if (tx[param] == null) {
     throw new ValidationError(
-      `${tx.TransactionType}: missing field ${paramName}`,
+      `${txType}: missing field ${String(paramNameStr)}`,
     )
   }
 
-  if (!checkValidity(tx[paramName])) {
+  if (!checkValidity(tx[param])) {
     throw new ValidationError(
-      `${tx.TransactionType}: invalid field ${paramName}`,
+      `${txType}: invalid field ${String(paramNameStr)}`,
     )
   }
 }
@@ -242,31 +338,50 @@ 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.
- * @throws
+ * @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 ValidationError if the parameter is invalid.
  */
-export function validateOptionalField(
-  tx: Record<string, unknown>,
-  paramName: string,
-  checkValidity: (inp: unknown) => boolean,
-): void {
-  if (tx[paramName] !== undefined && !checkValidity(tx[paramName])) {
+// eslint-disable-next-line max-params -- helper function
+export function validateOptionalField<
+  T extends Record<string, unknown>,
+  K extends keyof T,
+  V,
+>(
+  tx: T,
+  param: K,
+  checkValidity: (inp: unknown) => inp is V,
+  errorOpts: {
+    txType?: string
+    paramName?: string
+  } = {},
+): asserts tx is T & { [P in K]: V | undefined } {
+  const paramNameStr = errorOpts.paramName ?? param
+  const txType = errorOpts.txType ?? tx.TransactionType
+  if (tx[param] !== undefined && !checkValidity(tx[param])) {
     throw new ValidationError(
-      `${tx.TransactionType}: invalid field ${paramName}`,
+      `${txType}: invalid field ${String(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.
  */
-export interface BaseTransaction {
+export interface BaseTransaction extends Record<string, unknown> {
   /** The unique address of the transaction sender. */
   Account: Account
   /**
@@ -294,7 +409,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
@@ -351,8 +466,16 @@ export interface BaseTransaction {
  * @param common - An interface w/ common transaction fields.
  * @throws When the common param is malformed.
  */
-// eslint-disable-next-line max-statements -- lines required for validation
-export function validateBaseTransaction(common: Record<string, unknown>): void {
+// eslint-disable-next-line max-statements, max-lines-per-function -- lines required for validation
+export function validateBaseTransaction(
+  common: unknown,
+): asserts common is BaseTransaction {
+  if (!isRecord(common)) {
+    throw new ValidationError(
+      'BaseTransaction: invalid, expected a valid object',
+    )
+  }
+
   if (common.TransactionType === undefined) {
     throw new ValidationError('BaseTransaction: missing field TransactionType')
   }
@@ -362,7 +485,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)
@@ -375,18 +500,16 @@ export function validateBaseTransaction(common: Record<string, unknown>): void {
 
   validateOptionalField(common, 'LastLedgerSequence', isNumber)
 
-  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
-  const memos = common.Memos as Array<{ Memo?: unknown }> | undefined
-  if (memos !== undefined && !memos.every(isMemo)) {
+  const memos = common.Memos
+  if (memos != null && (!isArray(memos) || !memos.every(isMemo))) {
     throw new ValidationError('BaseTransaction: invalid Memos')
   }
 
-  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
-  const signers = common.Signers as Array<Record<string, unknown>> | undefined
+  const signers = common.Signers
 
   if (
-    signers !== undefined &&
-    (signers.length === 0 || !signers.every(isSigner))
+    signers != null &&
+    (!isArray(signers) || signers.length === 0 || !signers.every(isSigner))
   ) {
     throw new ValidationError('BaseTransaction: invalid Signers')
   }
@@ -433,7 +556,9 @@ export function parseAmountValue(amount: unknown): number {
  * @param tx A CredentialType Transaction.
  * @throws when the CredentialType is malformed.
  */
-export function validateCredentialType(tx: Record<string, unknown>): void {
+export function validateCredentialType<
+  T extends BaseTransaction & Record<string, unknown>,
+>(tx: T): void {
   if (typeof tx.TransactionType !== 'string') {
     throw new ValidationError('Invalid TransactionType')
   }
@@ -475,7 +600,7 @@ export function validateCredentialType(tx: Record<string, unknown>): void {
  *        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
+// eslint-disable-next-line max-params, max-lines-per-function -- separating logic further will add unnecessary complexity
 export function validateCredentialsList(
   credentials: unknown,
   transactionType: string,
@@ -485,7 +610,7 @@ export function validateCredentialsList(
   if (credentials == null) {
     return
   }
-  if (!Array.isArray(credentials)) {
+  if (!isArray(credentials)) {
     throw new ValidationError(
       `${transactionType}: Credentials must be an array`,
     )
@@ -512,7 +637,8 @@ export function validateCredentialsList(
       )
     }
   })
-  if (containsDuplicates(credentials)) {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+  if (containsDuplicates(credentials as string[] | AuthorizeCredential[])) {
     throw new ValidationError(
       `${transactionType}: Credentials cannot contain duplicate elements`,
     )
@@ -548,7 +674,6 @@ export function containsDuplicates(
   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
       }

package/src/models/transactions/delegateSet.ts

@@ -15,6 +15,7 @@ const NON_DELEGATABLE_TRANSACTIONS = new Set([
   'SignerListSet',
   'DelegateSet',
   'AccountDelete',
+  'Batch',
   // Pseudo transactions below:
   'EnableAmendment',
   'SetFee',

package/src/models/transactions/depositPreauth.ts

@@ -70,16 +70,14 @@ export function validateDepositPreauth(tx: Record<string, unknown>): void {
   } 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,
+      tx.TransactionType,
       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,
+      tx.TransactionType,
       false,
       MAX_AUTHORIZED_CREDENTIALS,
     )

package/src/models/transactions/escrowFinish.ts

@@ -55,8 +55,7 @@ export function validateEscrowFinish(tx: Record<string, unknown>): void {
 
   validateCredentialsList(
     tx.CredentialIDs,
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- known from base check
-    tx.TransactionType as string,
+    tx.TransactionType,
     true,
     MAX_AUTHORIZED_CREDENTIALS,
   )

package/src/models/transactions/index.ts

@@ -33,6 +33,7 @@ export {
   AMMWithdrawFlagsInterface,
   AMMWithdraw,
 } from './AMMWithdraw'
+export { Batch } from './batch'
 export { CheckCancel } from './checkCancel'
 export { CheckCash } from './checkCash'
 export { CheckCreate } from './checkCreate'
@@ -94,12 +95,25 @@ export {
 } from './paymentChannelClaim'
 export { PaymentChannelCreate } from './paymentChannelCreate'
 export { PaymentChannelFund } from './paymentChannelFund'
+export { PermissionedDomainSet } from './permissionedDomainSet'
+export { PermissionedDomainDelete } from './permissionedDomainDelete'
 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 { VaultClawback } from './vaultClawback'
+export {
+  VaultCreate,
+  VaultCreateFlags,
+  VaultCreateFlagsInterface,
+  VaultWithdrawalPolicy,
+} from './vaultCreate'
+export { VaultDelete } from './vaultDelete'
+export { VaultDeposit } from './vaultDeposit'
+export { VaultSet } from './vaultSet'
+export { VaultWithdraw } from './vaultWithdraw'
 export { XChainAddAccountCreateAttestation } from './XChainAddAccountCreateAttestation'
 export { XChainAddClaimAttestation } from './XChainAddClaimAttestation'
 export { XChainClaim } from './XChainClaim'
@@ -112,6 +126,3 @@ export {
   XChainModifyBridgeFlags,
   XChainModifyBridgeFlagsInterface,
 } from './XChainModifyBridge'
-
-export { PermissionedDomainSet } from './permissionedDomainSet'
-export { PermissionedDomainDelete } from './permissionedDomainDelete'

package/src/models/transactions/metadata.ts

@@ -88,6 +88,8 @@ export interface TransactionMetadataBase {
   delivered_amount?: Amount | MPTAmount | 'unavailable'
   TransactionIndex: number
   TransactionResult: string
+
+  ParentBatchID?: string
 }
 
 export type TransactionMetadata<T extends BaseTransaction = Transaction> =

package/src/models/transactions/offerCreate.ts

@@ -3,7 +3,7 @@ import { Amount } from '../common'
 
 import {
   BaseTransaction,
-  GlobalFlags,
+  GlobalFlagsInterface,
   validateBaseTransaction,
   isAmount,
 } from './common'
@@ -78,7 +78,7 @@ export enum OfferCreateFlags {
  * // }
  * ```
  */
-export interface OfferCreateFlagsInterface extends GlobalFlags {
+export interface OfferCreateFlagsInterface extends GlobalFlagsInterface {
   tfPassive?: boolean
   tfImmediateOrCancel?: boolean
   tfFillOrKill?: boolean