xrpl 4.3.0 → 4.4.0-smartescrow.0

package/src/models/transactions/transaction.ts

@@ -2,8 +2,6 @@
 /* eslint-disable max-lines-per-function -- need to work with a lot of Tx verifications */
 
 import { ValidationError } from '../../errors'
-import { IssuedCurrencyAmount, Memo } from '../common'
-import { isHex } from '../utils'
 import { convertTxFlagsToNumber } from '../utils/flags'
 
 import { AccountDelete, validateAccountDelete } from './accountDelete'
@@ -20,7 +18,11 @@ import { CheckCancel, validateCheckCancel } from './checkCancel'
 import { CheckCash, validateCheckCash } from './checkCash'
 import { CheckCreate, validateCheckCreate } from './checkCreate'
 import { Clawback, validateClawback } from './clawback'
-import { BaseTransaction, isIssuedCurrency } from './common'
+import {
+  BaseTransaction,
+  isIssuedCurrencyAmount,
+  validateBaseTransaction,
+} from './common'
 import { CredentialAccept, validateCredentialAccept } from './CredentialAccept'
 import { CredentialCreate, validateCredentialCreate } from './CredentialCreate'
 import { CredentialDelete, validateCredentialDelete } from './CredentialDelete'
@@ -92,6 +94,12 @@ import { SignerListSet, validateSignerListSet } from './signerListSet'
 import { TicketCreate, validateTicketCreate } from './ticketCreate'
 import { TrustSet, validateTrustSet } from './trustSet'
 import { UNLModify } from './UNLModify'
+import { VaultClawback, validateVaultClawback } from './vaultClawback'
+import { VaultCreate, validateVaultCreate } from './vaultCreate'
+import { VaultDelete, validateVaultDelete } from './vaultDelete'
+import { VaultDeposit, validateVaultDeposit } from './vaultDeposit'
+import { VaultSet, validateVaultSet } from './vaultSet'
+import { VaultWithdraw, validateVaultWithdraw } from './vaultWithdraw'
 import {
   XChainAccountCreateCommit,
   validateXChainAccountCreateCommit,
@@ -173,6 +181,12 @@ export type SubmittableTransaction =
   | SignerListSet
   | TicketCreate
   | TrustSet
+  | VaultClawback
+  | VaultCreate
+  | VaultDelete
+  | VaultDeposit
+  | VaultSet
+  | VaultWithdraw
   | XChainAccountCreateCommit
   | XChainAddAccountCreateAttestation
   | XChainAddClaimAttestation
@@ -216,50 +230,15 @@ export interface TransactionAndMetadata<
  */
 export function validate(transaction: Record<string, unknown>): void {
   const tx = { ...transaction }
-  if (tx.TransactionType == null) {
-    throw new ValidationError('Object does not have a `TransactionType`')
-  }
-  if (typeof tx.TransactionType !== 'string') {
-    throw new ValidationError("Object's `TransactionType` is not a string")
-  }
-
-  /*
-   * - Memos have exclusively hex data.
-   */
-  if (tx.Memos != null && typeof tx.Memos !== 'object') {
-    throw new ValidationError('Memo must be array')
-  }
-  if (tx.Memos != null) {
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- needed here
-    ;(tx.Memos as Array<Memo | null>).forEach((memo) => {
-      if (memo?.Memo == null) {
-        throw new ValidationError('Memo data must be in a `Memo` field')
-      }
-      if (memo.Memo.MemoData) {
-        if (!isHex(memo.Memo.MemoData)) {
-          throw new ValidationError('MemoData field must be a hex value')
-        }
-      }
-
-      if (memo.Memo.MemoType) {
-        if (!isHex(memo.Memo.MemoType)) {
-          throw new ValidationError('MemoType field must be a hex value')
-        }
-      }
 
-      if (memo.Memo.MemoFormat) {
-        if (!isHex(memo.Memo.MemoFormat)) {
-          throw new ValidationError('MemoFormat field must be a hex value')
-        }
-      }
-    })
-  }
+  // should already be done in the tx-specific validation, but doesn't hurt to check again
+  validateBaseTransaction(tx)
 
   Object.keys(tx).forEach((key) => {
     const standard_currency_code_len = 3
-    if (tx[key] && isIssuedCurrency(tx[key])) {
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- needed
-      const txCurrency = (tx[key] as IssuedCurrencyAmount).currency
+    const value = tx[key]
+    if (value && isIssuedCurrencyAmount(value)) {
+      const txCurrency = value.currency
 
       if (
         txCurrency.length === standard_currency_code_len &&
@@ -476,6 +455,30 @@ export function validate(transaction: Record<string, unknown>): void {
       validateTrustSet(tx)
       break
 
+    case 'VaultClawback':
+      validateVaultClawback(tx)
+      break
+
+    case 'VaultCreate':
+      validateVaultCreate(tx)
+      break
+
+    case 'VaultDelete':
+      validateVaultDelete(tx)
+      break
+
+    case 'VaultDeposit':
+      validateVaultDeposit(tx)
+      break
+
+    case 'VaultSet':
+      validateVaultSet(tx)
+      break
+
+    case 'VaultWithdraw':
+      validateVaultWithdraw(tx)
+      break
+
     case 'XChainAccountCreateCommit':
       validateXChainAccountCreateCommit(tx)
       break

package/src/models/transactions/vaultClawback.ts

@@ -0,0 +1,55 @@
+import { ClawbackAmount } from '../common'
+
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  validateRequiredField,
+  isString,
+  Account,
+  isAccount,
+  validateOptionalField,
+  isClawbackAmount,
+} from './common'
+
+/**
+ * The VaultClawback transaction performs a Clawback from the Vault, exchanging the shares of an account.
+ *
+ * Conceptually, the transaction performs VaultWithdraw on behalf of the Holder, sending the funds to the
+ * Issuer account of the asset. In case there are insufficient funds for the entire Amount the transaction
+ * will perform a partial Clawback, up to the Vault.AssetsAvailable. The Clawback transaction must respect
+ * any future fees or penalties.
+ *
+ * @category Transaction Models
+ */
+export interface VaultClawback extends BaseTransaction {
+  TransactionType: 'VaultClawback'
+
+  /**
+   * The ID of the vault from which assets are withdrawn.
+   */
+  VaultID: string
+
+  /**
+   * The account ID from which to clawback the assets.
+   */
+  Holder: Account
+
+  /**
+   * The asset amount to clawback. When Amount is 0 clawback all funds, up to the total shares the Holder owns.
+   */
+  Amount?: ClawbackAmount
+}
+
+/**
+ * Verify the form and type of a {@link VaultClawback} at runtime.
+ *
+ * @param tx - A {@link VaultClawback} Transaction.
+ * @throws When the {@link VaultClawback} is malformed.
+ */
+export function validateVaultClawback(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'VaultID', isString)
+  validateRequiredField(tx, 'Holder', isAccount)
+  validateOptionalField(tx, 'Amount', isClawbackAmount)
+}

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

@@ -20,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 '.'
@@ -63,6 +64,7 @@ const txToFlag = {
   PaymentChannelClaim: PaymentChannelClaimFlags,
   Payment: PaymentFlags,
   TrustSet: TrustSetFlags,
+  VaultCreate: VaultCreateFlags,
   XChainModifyBridge: XChainModifyBridgeFlags,
 }