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

package/src/models/transactions/vaultCreate.ts

@@ -0,0 +1,142 @@
+import { ValidationError } from '../../errors'
+import { Currency } from '../common'
+import { hasFlag, isHex } from '../utils'
+
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  GlobalFlagsInterface,
+  validateOptionalField,
+  isNumber,
+  isCurrency,
+  validateRequiredField,
+  isString,
+  VAULT_DATA_MAX_BYTE_LENGTH,
+  XRPLNumber,
+  isXRPLNumber,
+} from './common'
+
+const META_MAX_BYTE_LENGTH = 1024
+
+/**
+ * Enum representing withdrawal strategies for a Vault.
+ */
+export enum VaultWithdrawalPolicy {
+  vaultStrategyFirstComeFirstServe = 0x0001,
+}
+
+/**
+ * Enum representing values of {@link VaultCreate} transaction flags.
+ *
+ * @category Transaction Flags
+ */
+export enum VaultCreateFlags {
+  tfVaultPrivate = 0x00010000,
+  tfVaultShareNonTransferable = 0x00020000,
+}
+
+/**
+ * Map of flags to boolean values representing {@link VaultCreate} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface VaultCreateFlagsInterface extends GlobalFlagsInterface {
+  tfVaultPrivate?: boolean
+  tfVaultShareNonTransferable?: boolean
+}
+
+/**
+ * The VaultCreate transaction creates a new Vault object.
+ *
+ * @category Transaction Models
+ */
+export interface VaultCreate extends BaseTransaction {
+  TransactionType: 'VaultCreate'
+
+  /**
+   * The asset (XRP, IOU or MPT) of the Vault.
+   */
+  Asset: Currency
+
+  /**
+   * Arbitrary Vault metadata, limited to 256 bytes.
+   */
+  Data?: string
+
+  /**
+   * The maximum asset amount that can be held in a vault.
+   */
+  AssetsMaximum?: XRPLNumber
+
+  /**
+   * Arbitrary metadata about the share MPT, in hex format, limited to 1024 bytes.
+   */
+  MPTokenMetadata?: string
+
+  /**
+   * Indicates the withdrawal strategy used by the Vault.
+   */
+  WithdrawalPolicy?: number
+
+  /**
+   * The PermissionedDomain object ID associated with the shares of this Vault.
+   */
+  DomainID?: string
+}
+
+/**
+ * Verify the form and type of an {@link VaultCreate} at runtime.
+ *
+ * @param tx - A {@link VaultCreate} Transaction.
+ * @throws When the {@link VaultCreate} is malformed.
+ */
+// eslint-disable-next-line max-lines-per-function -- required to do all field validations
+export function validateVaultCreate(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'Asset', isCurrency)
+  validateOptionalField(tx, 'Data', isString)
+  validateOptionalField(tx, 'AssetsMaximum', isXRPLNumber)
+  validateOptionalField(tx, 'MPTokenMetadata', isString)
+  validateOptionalField(tx, 'WithdrawalPolicy', isNumber)
+  validateOptionalField(tx, 'DomainID', isString)
+
+  if (tx.Data !== undefined) {
+    const dataHex = tx.Data
+    if (!isHex(dataHex)) {
+      throw new ValidationError('VaultCreate: Data must be a valid hex string')
+    }
+    const dataByteLength = dataHex.length / 2
+    if (dataByteLength > VAULT_DATA_MAX_BYTE_LENGTH) {
+      throw new ValidationError(
+        `VaultCreate: Data exceeds ${VAULT_DATA_MAX_BYTE_LENGTH} bytes (actual: ${dataByteLength})`,
+      )
+    }
+  }
+
+  if (tx.MPTokenMetadata !== undefined) {
+    const metaHex = tx.MPTokenMetadata
+    if (!isHex(metaHex)) {
+      throw new ValidationError(
+        'VaultCreate: MPTokenMetadata must be a valid hex string',
+      )
+    }
+    const metaByteLength = metaHex.length / 2
+    if (metaByteLength > META_MAX_BYTE_LENGTH) {
+      throw new ValidationError(
+        `VaultCreate: MPTokenMetadata exceeds ${META_MAX_BYTE_LENGTH} bytes (actual: ${metaByteLength})`,
+      )
+    }
+  }
+
+  // If DomainID present, tfVaultPrivate must be set
+  if (
+    tx.DomainID !== undefined &&
+    !hasFlag(tx, VaultCreateFlags.tfVaultPrivate, 'tfVaultPrivate')
+  ) {
+    throw new ValidationError(
+      'VaultCreate: Cannot set DomainID unless tfVaultPrivate flag is set.',
+    )
+  }
+}

package/src/models/transactions/vaultDelete.ts

@@ -0,0 +1,32 @@
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  validateRequiredField,
+  isString,
+} from './common'
+
+/**
+ * The VaultDelete transaction deletes an existing vault object.
+ *
+ * @category Transaction Models
+ */
+export interface VaultDelete extends BaseTransaction {
+  TransactionType: 'VaultDelete'
+
+  /**
+   * The ID of the vault to be deleted.
+   */
+  VaultID: string
+}
+
+/**
+ * Verify the form and type of a {@link VaultDelete} at runtime.
+ *
+ * @param tx - A {@link VaultDelete} Transaction.
+ * @throws When the {@link VaultDelete} is malformed.
+ */
+export function validateVaultDelete(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'VaultID', isString)
+}

package/src/models/transactions/vaultDeposit.ts

@@ -0,0 +1,41 @@
+import { Amount } from '../common'
+
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  validateRequiredField,
+  isString,
+  isAmount,
+} from './common'
+
+/**
+ * The VaultDeposit transaction adds liqudity in exchange for vault shares.
+ *
+ * @category Transaction Models
+ */
+export interface VaultDeposit extends BaseTransaction {
+  TransactionType: 'VaultDeposit'
+
+  /**
+   * The ID of the vault to which the assets are deposited.
+   */
+  VaultID: string
+
+  /**
+   * Asset amount to deposit.
+   */
+  Amount: Amount
+}
+
+/**
+ * Verify the form and type of a {@link VaultDeposit} at runtime.
+ *
+ * @param tx - A {@link VaultDeposit} Transaction.
+ * @throws When the {@link VaultDeposit} is malformed.
+ */
+export function validateVaultDeposit(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'VaultID', isString)
+  validateRequiredField(tx, 'Amount', isAmount)
+}

package/src/models/transactions/vaultSet.ts

@@ -0,0 +1,71 @@
+import { ValidationError } from '../../errors'
+import { isHex } from '../utils'
+
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  validateOptionalField,
+  validateRequiredField,
+  isString,
+  VAULT_DATA_MAX_BYTE_LENGTH,
+  XRPLNumber,
+  isXRPLNumber,
+} from './common'
+
+/**
+ * The VaultSet transaction modifies mutable fields on an existing Vault object.
+ *
+ * @category Transaction Models
+ */
+export interface VaultSet extends BaseTransaction {
+  TransactionType: 'VaultSet'
+
+  /**
+   * The ID of the Vault to be modified. Must be included when updating the Vault.
+   */
+  VaultID: string
+
+  /**
+   * Arbitrary Vault metadata, limited to 256 bytes.
+   */
+  Data?: string
+
+  /**
+   * The maximum asset amount that can be held in a vault. The value cannot be lower than the
+   * current AssetsTotal unless the value is 0.
+   */
+  AssetsMaximum?: XRPLNumber
+
+  /**
+   * The PermissionedDomain object ID associated with the shares of this Vault.
+   */
+  DomainID?: string
+}
+
+/**
+ * Verify the form and type of a {@link VaultSet} at runtime.
+ *
+ * @param tx - A {@link VaultSet} Transaction.
+ * @throws When the {@link VaultSet} is malformed.
+ */
+export function validateVaultSet(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'VaultID', isString)
+  validateOptionalField(tx, 'Data', isString)
+  validateOptionalField(tx, 'AssetsMaximum', isXRPLNumber)
+  validateOptionalField(tx, 'DomainID', isString)
+
+  if (tx.Data !== undefined) {
+    const dataHex = tx.Data
+    if (!isHex(dataHex)) {
+      throw new ValidationError('VaultSet: Data must be a valid hex string')
+    }
+    const dataByteLength = dataHex.length / 2
+    if (dataByteLength > VAULT_DATA_MAX_BYTE_LENGTH) {
+      throw new ValidationError(
+        `VaultSet: Data exceeds ${VAULT_DATA_MAX_BYTE_LENGTH} bytes (actual: ${dataByteLength})`,
+      )
+    }
+  }
+}

package/src/models/transactions/vaultWithdraw.ts

@@ -0,0 +1,50 @@
+import { Amount } from '../common'
+
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  validateRequiredField,
+  isString,
+  isAmount,
+  Account,
+  validateOptionalField,
+  isAccount,
+} from './common'
+
+/**
+ * The VaultWithdraw transaction withdraws assets in exchange for the vault's shares.
+ *
+ * @category Transaction Models
+ */
+export interface VaultWithdraw extends BaseTransaction {
+  TransactionType: 'VaultWithdraw'
+
+  /**
+   * The ID of the vault from which assets are withdrawn.
+   */
+  VaultID: string
+
+  /**
+   * The exact amount of Vault asset to withdraw.
+   */
+  Amount: Amount
+
+  /**
+   * An account to receive the assets. It must be able to receive the asset.
+   */
+  Destination?: Account
+}
+
+/**
+ * Verify the form and type of a {@link VaultWithdraw} at runtime.
+ *
+ * @param tx - A {@link VaultWithdraw} Transaction.
+ * @throws When the {@link VaultWithdraw} is malformed.
+ */
+export function validateVaultWithdraw(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'VaultID', isString)
+  validateRequiredField(tx, 'Amount', isAmount)
+  validateOptionalField(tx, 'Destination', isAccount)
+}

package/src/models/utils/flags.ts

@@ -8,6 +8,8 @@ import { AccountSetTfFlags } from '../transactions/accountSet'
 import { AMMClawbackFlags } from '../transactions/AMMClawback'
 import { AMMDepositFlags } from '../transactions/AMMDeposit'
 import { AMMWithdrawFlags } from '../transactions/AMMWithdraw'
+import { BatchFlags } from '../transactions/batch'
+import { GlobalFlags } from '../transactions/common'
 import { MPTokenAuthorizeFlags } from '../transactions/MPTokenAuthorize'
 import { MPTokenIssuanceCreateFlags } from '../transactions/MPTokenIssuanceCreate'
 import { MPTokenIssuanceSetFlags } from '../transactions/MPTokenIssuanceSet'
@@ -18,6 +20,7 @@ import { PaymentFlags } from '../transactions/payment'
 import { PaymentChannelClaimFlags } from '../transactions/paymentChannelClaim'
 import type { Transaction } from '../transactions/transaction'
 import { TrustSetFlags } from '../transactions/trustSet'
+import { VaultCreateFlags } from '../transactions/vaultCreate'
 import { XChainModifyBridgeFlags } from '../transactions/XChainModifyBridge'
 
 import { isFlagEnabled } from '.'
@@ -51,6 +54,7 @@ const txToFlag = {
   AMMClawback: AMMClawbackFlags,
   AMMDeposit: AMMDepositFlags,
   AMMWithdraw: AMMWithdrawFlags,
+  Batch: BatchFlags,
   MPTokenAuthorize: MPTokenAuthorizeFlags,
   MPTokenIssuanceCreate: MPTokenIssuanceCreateFlags,
   MPTokenIssuanceSet: MPTokenIssuanceSetFlags,
@@ -60,6 +64,7 @@ const txToFlag = {
   PaymentChannelClaim: PaymentChannelClaimFlags,
   Payment: PaymentFlags,
   TrustSet: TrustSetFlags,
+  VaultCreate: VaultCreateFlags,
   XChainModifyBridge: XChainModifyBridgeFlags,
 }
 
@@ -97,27 +102,36 @@ export function setTransactionFlagsToNumber(tx: Transaction): void {
  * @returns A numerical representation of a Transaction's Flags
  */
 export function convertTxFlagsToNumber(tx: Transaction): number {
-  if (!tx.Flags) {
+  const txFlags = tx.Flags
+  if (txFlags == null) {
     return 0
   }
-  if (typeof tx.Flags === 'number') {
-    return tx.Flags
+  if (typeof txFlags === 'number') {
+    return txFlags
   }
 
   if (isTxToFlagKey(tx.TransactionType)) {
     const flagEnum = txToFlag[tx.TransactionType]
-    return Object.keys(tx.Flags).reduce((resultFlags, flag) => {
-      if (flagEnum[flag] == null) {
-        throw new ValidationError(
-          `Invalid flag ${flag}. Valid flags are ${JSON.stringify(flagEnum)}`,
-        )
+    return Object.keys(txFlags).reduce((resultFlags, flag) => {
+      if (flagEnum[flag] == null && GlobalFlags[flag] == null) {
+        throw new ValidationError(`Invalid flag ${flag}.`)
       }
 
-      return tx.Flags?.[flag] ? resultFlags | flagEnum[flag] : resultFlags
+      return txFlags[flag]
+        ? resultFlags | (flagEnum[flag] || GlobalFlags[flag])
+        : resultFlags
     }, 0)
   }
 
-  return 0
+  return Object.keys(txFlags).reduce((resultFlags, flag) => {
+    if (GlobalFlags[flag] == null) {
+      throw new ValidationError(
+        `Invalid flag ${flag}. Valid flags are ${JSON.stringify(GlobalFlags)}`,
+      )
+    }
+
+    return txFlags[flag] ? resultFlags | GlobalFlags[flag] : resultFlags
+  }, 0)
 }
 
 /**
@@ -146,5 +160,11 @@ export function parseTransactionFlags(tx: Transaction): object {
     })
   }
 
+  Object.values(GlobalFlags).forEach((flag) => {
+    if (typeof flag === 'string' && isFlagEnabled(flags, GlobalFlags[flag])) {
+      booleanFlagMap[flag] = true
+    }
+  })
+
   return booleanFlagMap
 }

package/src/models/utils/index.ts

@@ -1,3 +1,5 @@
+import type { Transaction } from '../transactions'
+
 const HEX_REGEX = /^[0-9A-Fa-f]+$/u
 export const INTEGER_SANITY_CHECK = /^[0-9]+$/u
 
@@ -27,6 +29,28 @@ export function isFlagEnabled(Flags: number, checkFlag: number): boolean {
   return (BigInt(checkFlag) & BigInt(Flags)) === BigInt(checkFlag)
 }
 
+/**
+ * Determines whether a transaction has a certain flag enabled.
+ *
+ * @param tx The transaction to check for the flag.
+ * @param flag The flag to check.
+ * @param flagName The name of the flag to check, used for object flags.
+ * @returns Whether `flag` is enabled on `tx`.
+ */
+export function hasFlag(
+  tx: Transaction | Record<string, unknown>,
+  flag: number,
+  flagName: string,
+): boolean {
+  if (tx.Flags == null) {
+    return false
+  }
+  if (typeof tx.Flags === 'number') {
+    return isFlagEnabled(tx.Flags, flag)
+  }
+  return tx.Flags[flagName] === true
+}
+
 /**
  * Check if string is in hex format.
  *