xrpl 4.3.0-smartescrow.2 → 4.3.0

package/src/models/transactions/batch.ts

@@ -0,0 +1,151 @@
+import { ValidationError } from '../../errors'
+import { Signer } from '../common'
+import { hasFlag } from '../utils'
+
+import {
+  BaseTransaction,
+  GlobalFlags,
+  GlobalFlagsInterface,
+  isArray,
+  isRecord,
+  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)
+
+  tx.RawTransactions.forEach((rawTxObj, index) => {
+    if (!isRecord(rawTxObj)) {
+      throw new ValidationError(
+        `Batch: RawTransactions[${index}] is not object.`,
+      )
+    }
+    validateRequiredField(rawTxObj, 'RawTransaction', isRecord, {
+      paramName: `RawTransactions[${index}].RawTransaction`,
+      txType: 'Batch',
+    })
+
+    const rawTx = rawTxObj.RawTransaction
+    if (rawTx.TransactionType === 'Batch') {
+      throw new ValidationError(
+        `Batch: RawTransactions[${index}] is a Batch transaction. Cannot nest Batch transactions.`,
+      )
+    }
+
+    // Check for the `tfInnerBatchTxn` flag in the inner transactions
+    if (!hasFlag(rawTx, GlobalFlags.tfInnerBatchTxn, 'tfInnerBatchTxn')) {
+      throw new ValidationError(
+        `Batch: RawTransactions[${index}] must contain the \`tfInnerBatchTxn\` flag.`,
+      )
+    }
+
+    // Full validation of each `RawTransaction` object is done in `validate` to avoid dependency cycles
+  })
+
+  validateOptionalField(tx, 'BatchSigners', isArray)
+
+  tx.BatchSigners?.forEach((signerObj, index) => {
+    if (!isRecord(signerObj)) {
+      throw new ValidationError(`Batch: BatchSigners[${index}] is not object.`)
+    }
+
+    const signerRecord = signerObj
+    validateRequiredField(signerRecord, 'BatchSigner', isRecord, {
+      paramName: `BatchSigners[${index}].BatchSigner`,
+      txType: 'Batch',
+    })
+
+    const signer = signerRecord.BatchSigner
+    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/common.ts

@@ -69,7 +69,13 @@ const XCHAIN_BRIDGE_SIZE = 4
 const MPTOKEN_SIZE = 2
 const AUTHORIZE_CREDENTIAL_SIZE = 1
 
-function isRecord(value: unknown): value is Record<string, unknown> {
+/**
+ * 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'
 }
 
@@ -210,30 +216,54 @@ export function isXChainBridge(input: unknown): input is XChainBridge {
   )
 }
 
+/**
+ * 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 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 +272,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 +343,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
@@ -337,6 +386,10 @@ export interface BaseTransaction {
    * The network id of the transaction.
    */
   NetworkID?: number
+  /**
+   * The delegate account that is sending the transaction.
+   */
+  Delegate?: Account
 }
 
 /**
@@ -347,7 +400,10 @@ export interface BaseTransaction {
  * @param common - An interface w/ common transaction fields.
  * @throws When the common param is malformed.
  */
-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: Record<string, unknown>,
+): asserts common is BaseTransaction {
   if (common.TransactionType === undefined) {
     throw new ValidationError('BaseTransaction: missing field TransactionType')
   }
@@ -357,7 +413,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)
@@ -395,6 +453,15 @@ export function validateBaseTransaction(common: Record<string, unknown>): void {
   validateOptionalField(common, 'TxnSignature', isString)
 
   validateOptionalField(common, 'NetworkID', isNumber)
+
+  validateOptionalField(common, 'Delegate', isAccount)
+
+  const delegate = common.Delegate
+  if (delegate != null && delegate === common.Account) {
+    throw new ValidationError(
+      'BaseTransaction: Account and Delegate addresses cannot be the same',
+    )
+  }
 }
 
 /**
@@ -534,7 +601,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

@@ -0,0 +1,112 @@
+import { ValidationError } from '../../errors'
+
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  validateRequiredField,
+  isAccount,
+  Account,
+} from './common'
+
+const PERMISSIONS_MAX_LENGTH = 10
+const NON_DELEGATABLE_TRANSACTIONS = new Set([
+  'AccountSet',
+  'SetRegularKey',
+  'SignerListSet',
+  'DelegateSet',
+  'AccountDelete',
+  'Batch',
+  // Pseudo transactions below:
+  'EnableAmendment',
+  'SetFee',
+  'UNLModify',
+])
+
+export interface Permission {
+  Permission: {
+    PermissionValue: string
+  }
+}
+
+/**
+ * DelegateSet allows an account to delegate a set of permissions to another account.
+ *
+ * @category Transaction Models
+ */
+export interface DelegateSet extends BaseTransaction {
+  TransactionType: 'DelegateSet'
+
+  /**
+   * The authorized account.
+   */
+  Authorize: Account
+
+  /**
+   * The transaction permissions (represented by integers) that the account has been granted.
+   */
+  Permissions: Permission[]
+}
+
+/**
+ * Verify the form and type of an DelegateSet at runtime.
+ *
+ * @param tx - An DelegateSet Transaction.
+ * @throws When the DelegateSet is malformed.
+ */
+// eslint-disable-next-line max-lines-per-function -- necessary for validation
+export function validateDelegateSet(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'Authorize', isAccount)
+
+  if (tx.Authorize === tx.Account) {
+    throw new ValidationError(
+      'DelegateSet: Authorize and Account must be different.',
+    )
+  }
+
+  validateRequiredField(tx, 'Permissions', Array.isArray)
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- required for validation
+  const permissions = tx.Permissions as DelegateSet['Permissions']
+  if (permissions.length > PERMISSIONS_MAX_LENGTH) {
+    throw new ValidationError(
+      `DelegateSet: Permissions array length cannot be greater than ${PERMISSIONS_MAX_LENGTH}.`,
+    )
+  }
+
+  const permissionValueSet = new Set()
+  permissions.forEach((permission: Permission) => {
+    if (
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- required for validation
+      permission == null ||
+      Object.keys(permission).length !== 1 ||
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- required for validation
+      permission.Permission == null ||
+      Object.keys(permission.Permission).length !== 1
+    ) {
+      throw new ValidationError(
+        'DelegateSet: Permissions array element is malformed',
+      )
+    }
+    const permissionValue = permission.Permission.PermissionValue
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- required for validation
+    if (permissionValue == null) {
+      throw new ValidationError('DelegateSet: PermissionValue must be defined')
+    }
+    if (typeof permissionValue !== 'string') {
+      throw new ValidationError('DelegateSet: PermissionValue must be a string')
+    }
+    if (NON_DELEGATABLE_TRANSACTIONS.has(permissionValue)) {
+      throw new ValidationError(
+        `DelegateSet: PermissionValue contains a non-delegatable transaction ${permissionValue}`,
+      )
+    }
+    permissionValueSet.add(permissionValue)
+  })
+  if (permissions.length !== permissionValueSet.size) {
+    throw new ValidationError(
+      'DelegateSet: Permissions array cannot contain duplicate values',
+    )
+  }
+}

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/escrowCreate.ts

@@ -47,10 +47,6 @@ export interface EscrowCreate extends BaseTransaction {
    * payment, such as a hosted recipient at the destination address.
    */
   DestinationTag?: number
-
-  FinishFunction?: string
-
-  Data?: string
 }
 
 /**
@@ -79,13 +75,9 @@ export function validateEscrowCreate(tx: Record<string, unknown>): void {
     )
   }
 
-  if (
-    tx.FinishAfter === undefined &&
-    tx.Condition === undefined &&
-    tx.FinishFunction === undefined
-  ) {
+  if (tx.FinishAfter === undefined && tx.Condition === undefined) {
     throw new ValidationError(
-      'EscrowCreate: Either FinishAfter, Condition, or FinishFunction must be specified',
+      'EscrowCreate: Either Condition or FinishAfter must be specified',
     )
   }
 

package/src/models/transactions/escrowFinish.ts

@@ -38,8 +38,6 @@ export interface EscrowFinish extends BaseTransaction {
    * The credentials included must not be expired.
    */
   CredentialIDs?: string[]
-
-  ComputationAllowance?: number
 }
 
 /**
@@ -55,8 +53,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'
@@ -42,6 +43,7 @@ export { CredentialCreate } from './CredentialCreate'
 export { CredentialDelete } from './CredentialDelete'
 export { DIDDelete } from './DIDDelete'
 export { DIDSet } from './DIDSet'
+export { DelegateSet, Permission } from './delegateSet'
 export { DepositPreauth } from './depositPreauth'
 export { EscrowCancel } from './escrowCancel'
 export { EscrowCreate } from './escrowCreate'
@@ -99,6 +101,8 @@ export { SignerListSet } from './signerListSet'
 export { TicketCreate } from './ticketCreate'
 export { TrustSetFlagsInterface, TrustSetFlags, TrustSet } from './trustSet'
 export { UNLModify } from './UNLModify'
+export { PermissionedDomainSet } from './permissionedDomainSet'
+export { PermissionedDomainDelete } from './permissionedDomainDelete'
 export { XChainAddAccountCreateAttestation } from './XChainAddAccountCreateAttestation'
 export { XChainAddClaimAttestation } from './XChainAddClaimAttestation'
 export { XChainClaim } from './XChainClaim'
@@ -111,6 +115,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