xrpl 4.0.0 → 4.1.0

package/src/models/transactions/MPTokenAuthorize.ts

@@ -0,0 +1,67 @@
+import {
+  BaseTransaction,
+  isString,
+  validateBaseTransaction,
+  validateRequiredField,
+  Account,
+  validateOptionalField,
+  isAccount,
+  GlobalFlags,
+} from './common'
+
+/**
+ * Transaction Flags for an MPTokenAuthorize Transaction.
+ *
+ * @category Transaction Flags
+ */
+export enum MPTokenAuthorizeFlags {
+  /**
+   * If set and transaction is submitted by a holder, it indicates that the holder no
+   * longer wants to hold the MPToken, which will be deleted as a result. If the the holder's
+   * MPToken has non-zero balance while trying to set this flag, the transaction will fail. On
+   * the other hand, if set and transaction is submitted by an issuer, it would mean that the
+   * issuer wants to unauthorize the holder (only applicable for allow-listing),
+   * which would unset the lsfMPTAuthorized flag on the MPToken.
+   */
+  tfMPTUnauthorize = 0x00000001,
+}
+
+/**
+ * Map of flags to boolean values representing {@link MPTokenAuthorize} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface MPTokenAuthorizeFlagsInterface extends GlobalFlags {
+  tfMPTUnauthorize?: boolean
+}
+
+/**
+ * The MPTokenAuthorize transaction is used to globally lock/unlock a MPTokenIssuance,
+ * or lock/unlock an individual's MPToken.
+ */
+export interface MPTokenAuthorize extends BaseTransaction {
+  TransactionType: 'MPTokenAuthorize'
+  /**
+   * Identifies the MPTokenIssuance
+   */
+  MPTokenIssuanceID: string
+  /**
+   * An optional XRPL Address of an individual token holder balance to lock/unlock.
+   * If omitted, this transaction will apply to all any accounts holding MPTs.
+   */
+  Holder?: Account
+  Flags?: number | MPTokenAuthorizeFlagsInterface
+}
+
+/**
+ * Verify the form and type of an MPTokenAuthorize at runtime.
+ *
+ * @param tx - An MPTokenAuthorize Transaction.
+ * @throws When the MPTokenAuthorize is Malformed.
+ */
+export function validateMPTokenAuthorize(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+  validateRequiredField(tx, 'MPTokenIssuanceID', isString)
+  validateOptionalField(tx, 'Holder', isAccount)
+}

package/src/models/transactions/MPTokenIssuanceCreate.ts

@@ -0,0 +1,179 @@
+import { ValidationError } from '../../errors'
+import { isHex, INTEGER_SANITY_CHECK, isFlagEnabled } from '../utils'
+
+import {
+  BaseTransaction,
+  GlobalFlags,
+  validateBaseTransaction,
+  validateOptionalField,
+  isString,
+  isNumber,
+} from './common'
+import type { TransactionMetadataBase } from './metadata'
+
+// 2^63 - 1
+const MAX_AMT = '9223372036854775807'
+const MAX_TRANSFER_FEE = 50000
+
+/**
+ * Transaction Flags for an MPTokenIssuanceCreate Transaction.
+ *
+ * @category Transaction Flags
+ */
+export enum MPTokenIssuanceCreateFlags {
+  /**
+   * If set, indicates that the MPT can be locked both individually and globally.
+   * If not set, the MPT cannot be locked in any way.
+   */
+  tfMPTCanLock = 0x00000002,
+  /**
+   * If set, indicates that individual holders must be authorized.
+   * This enables issuers to limit who can hold their assets.
+   */
+  tfMPTRequireAuth = 0x00000004,
+  /**
+   * If set, indicates that individual holders can place their balances into an escrow.
+   */
+  tfMPTCanEscrow = 0x00000008,
+  /**
+   * If set, indicates that individual holders can trade their balances
+   *  using the XRP Ledger DEX or AMM.
+   */
+  tfMPTCanTrade = 0x00000010,
+  /**
+   * If set, indicates that tokens may be transferred to other accounts
+   *  that are not the issuer.
+   */
+  tfMPTCanTransfer = 0x00000020,
+  /**
+   * If set, indicates that the issuer may use the Clawback transaction
+   * to clawback value from individual holders.
+   */
+  tfMPTCanClawback = 0x00000040,
+}
+
+/**
+ * Map of flags to boolean values representing {@link MPTokenIssuanceCreate} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface MPTokenIssuanceCreateFlagsInterface extends GlobalFlags {
+  tfMPTCanLock?: boolean
+  tfMPTRequireAuth?: boolean
+  tfMPTCanEscrow?: boolean
+  tfMPTCanTrade?: boolean
+  tfMPTCanTransfer?: boolean
+  tfMPTCanClawback?: boolean
+}
+
+/**
+ * The MPTokenIssuanceCreate transaction creates a MPTokenIssuance object
+ * and adds it to the relevant directory node of the creator account.
+ * This transaction is the only opportunity an issuer has to specify any token fields
+ * that are defined as immutable (e.g., MPT Flags). If the transaction is successful,
+ * the newly created token will be owned by the account (the creator account) which
+ * executed the transaction.
+ */
+export interface MPTokenIssuanceCreate extends BaseTransaction {
+  TransactionType: 'MPTokenIssuanceCreate'
+  /**
+   * An asset scale is the difference, in orders of magnitude, between a standard unit and
+   * a corresponding fractional unit. More formally, the asset scale is a non-negative integer
+   * (0, 1, 2, …) such that one standard unit equals 10^(-scale) of a corresponding
+   * fractional unit. If the fractional unit equals the standard unit, then the asset scale is 0.
+   * Note that this value is optional, and will default to 0 if not supplied.
+   */
+  AssetScale?: number
+  /**
+   * Specifies the maximum asset amount of this token that should ever be issued.
+   * It is a non-negative integer string that can store a range of up to 63 bits. If not set, the max
+   * amount will default to the largest unsigned 63-bit integer (0x7FFFFFFFFFFFFFFF or 9223372036854775807)
+   *
+   * Example:
+   * ```
+   * MaximumAmount: '9223372036854775807'
+   * ```
+   */
+  MaximumAmount?: string
+  /**
+   * Specifies the fee to charged by the issuer for secondary sales of the Token,
+   * if such sales are allowed. Valid values for this field are between 0 and 50,000 inclusive,
+   * allowing transfer rates of between 0.000% and 50.000% in increments of 0.001.
+   * The field must NOT be present if the `tfMPTCanTransfer` flag is not set.
+   */
+  TransferFee?: number
+  /**
+   * Arbitrary metadata about this issuance, in hex format.
+   */
+  MPTokenMetadata?: string | null
+  Flags?: number | MPTokenIssuanceCreateFlagsInterface
+}
+
+export interface MPTokenIssuanceCreateMetadata extends TransactionMetadataBase {
+  mpt_issuance_id?: string
+}
+
+/* eslint-disable max-lines-per-function -- Not needed to reduce function */
+/**
+ * Verify the form and type of an MPTokenIssuanceCreate at runtime.
+ *
+ * @param tx - An MPTokenIssuanceCreate Transaction.
+ * @throws When the MPTokenIssuanceCreate is Malformed.
+ */
+export function validateMPTokenIssuanceCreate(
+  tx: Record<string, unknown>,
+): void {
+  validateBaseTransaction(tx)
+  validateOptionalField(tx, 'MaximumAmount', isString)
+  validateOptionalField(tx, 'MPTokenMetadata', isString)
+  validateOptionalField(tx, 'TransferFee', isNumber)
+  validateOptionalField(tx, 'AssetScale', isNumber)
+
+  if (typeof tx.MPTokenMetadata === 'string' && tx.MPTokenMetadata === '') {
+    throw new ValidationError(
+      'MPTokenIssuanceCreate: MPTokenMetadata must not be empty string',
+    )
+  }
+
+  if (typeof tx.MPTokenMetadata === 'string' && !isHex(tx.MPTokenMetadata)) {
+    throw new ValidationError(
+      'MPTokenIssuanceCreate: MPTokenMetadata must be in hex format',
+    )
+  }
+
+  if (typeof tx.MaximumAmount === 'string') {
+    if (!INTEGER_SANITY_CHECK.exec(tx.MaximumAmount)) {
+      throw new ValidationError('MPTokenIssuanceCreate: Invalid MaximumAmount')
+    } else if (
+      BigInt(tx.MaximumAmount) > BigInt(MAX_AMT) ||
+      BigInt(tx.MaximumAmount) < BigInt(`0`)
+    ) {
+      throw new ValidationError(
+        'MPTokenIssuanceCreate: MaximumAmount out of range',
+      )
+    }
+  }
+
+  if (typeof tx.TransferFee === 'number') {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Not necessary
+    const flags = tx.Flags as number | MPTokenIssuanceCreateFlagsInterface
+    const isTfMPTCanTransfer =
+      typeof flags === 'number'
+        ? isFlagEnabled(flags, MPTokenIssuanceCreateFlags.tfMPTCanTransfer)
+        : flags.tfMPTCanTransfer ?? false
+
+    if (tx.TransferFee < 0 || tx.TransferFee > MAX_TRANSFER_FEE) {
+      throw new ValidationError(
+        `MPTokenIssuanceCreate: TransferFee must be between 0 and ${MAX_TRANSFER_FEE}`,
+      )
+    }
+
+    if (tx.TransferFee && !isTfMPTCanTransfer) {
+      throw new ValidationError(
+        'MPTokenIssuanceCreate: TransferFee cannot be provided without enabling tfMPTCanTransfer flag',
+      )
+    }
+  }
+}
+/* eslint-enable max-lines-per-function */

package/src/models/transactions/MPTokenIssuanceDestroy.ts

@@ -0,0 +1,34 @@
+import {
+  BaseTransaction,
+  isString,
+  validateBaseTransaction,
+  validateRequiredField,
+} from './common'
+
+/**
+ * The MPTokenIssuanceDestroy transaction is used to remove an MPTokenIssuance object
+ * from the directory node in which it is being held, effectively removing the token
+ * from the ledger. If this operation succeeds, the corresponding
+ * MPTokenIssuance is removed and the owner’s reserve requirement is reduced by one.
+ * This operation must fail if there are any holders who have non-zero balances.
+ */
+export interface MPTokenIssuanceDestroy extends BaseTransaction {
+  TransactionType: 'MPTokenIssuanceDestroy'
+  /**
+   * Identifies the MPTokenIssuance object to be removed by the transaction.
+   */
+  MPTokenIssuanceID: string
+}
+
+/**
+ * Verify the form and type of an MPTokenIssuanceDestroy at runtime.
+ *
+ * @param tx - An MPTokenIssuanceDestroy Transaction.
+ * @throws When the MPTokenIssuanceDestroy is Malformed.
+ */
+export function validateMPTokenIssuanceDestroy(
+  tx: Record<string, unknown>,
+): void {
+  validateBaseTransaction(tx)
+  validateRequiredField(tx, 'MPTokenIssuanceID', isString)
+}

package/src/models/transactions/MPTokenIssuanceSet.ts

@@ -0,0 +1,86 @@
+import { ValidationError } from '../../errors'
+import { isFlagEnabled } from '../utils'
+
+import {
+  BaseTransaction,
+  isString,
+  validateBaseTransaction,
+  validateRequiredField,
+  Account,
+  validateOptionalField,
+  isAccount,
+  GlobalFlags,
+} from './common'
+
+/**
+ * Transaction Flags for an MPTokenIssuanceSet Transaction.
+ *
+ * @category Transaction Flags
+ */
+export enum MPTokenIssuanceSetFlags {
+  /**
+   * If set, indicates that issuer locks the MPT
+   */
+  tfMPTLock = 0x00000001,
+  /**
+   * If set, indicates that issuer unlocks the MPT
+   */
+  tfMPTUnlock = 0x00000002,
+}
+
+/**
+ * Map of flags to boolean values representing {@link MPTokenIssuanceSet} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface MPTokenIssuanceSetFlagsInterface extends GlobalFlags {
+  tfMPTLock?: boolean
+  tfMPTUnlock?: boolean
+}
+
+/**
+ * The MPTokenIssuanceSet transaction is used to globally lock/unlock a MPTokenIssuance,
+ * or lock/unlock an individual's MPToken.
+ */
+export interface MPTokenIssuanceSet extends BaseTransaction {
+  TransactionType: 'MPTokenIssuanceSet'
+  /**
+   * Identifies the MPTokenIssuance
+   */
+  MPTokenIssuanceID: string
+  /**
+   * An optional XRPL Address of an individual token holder balance to lock/unlock.
+   * If omitted, this transaction will apply to all any accounts holding MPTs.
+   */
+  Holder?: Account
+  Flags?: number | MPTokenIssuanceSetFlagsInterface
+}
+
+/**
+ * Verify the form and type of an MPTokenIssuanceSet at runtime.
+ *
+ * @param tx - An MPTokenIssuanceSet Transaction.
+ * @throws When the MPTokenIssuanceSet is Malformed.
+ */
+export function validateMPTokenIssuanceSet(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+  validateRequiredField(tx, 'MPTokenIssuanceID', isString)
+  validateOptionalField(tx, 'Holder', isAccount)
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Not necessary
+  const flags = tx.Flags as number | MPTokenIssuanceSetFlagsInterface
+  const isTfMPTLock =
+    typeof flags === 'number'
+      ? isFlagEnabled(flags, MPTokenIssuanceSetFlags.tfMPTLock)
+      : flags.tfMPTLock ?? false
+
+  const isTfMPTUnlock =
+    typeof flags === 'number'
+      ? isFlagEnabled(flags, MPTokenIssuanceSetFlags.tfMPTUnlock)
+      : flags.tfMPTUnlock ?? false
+
+  if (isTfMPTLock && isTfMPTUnlock) {
+    throw new ValidationError('MPTokenIssuanceSet: flag conflict')
+  }
+}

package/src/models/transactions/accountDelete.ts

@@ -4,6 +4,7 @@ import {
   isAccount,
   isNumber,
   validateBaseTransaction,
+  validateCredentialsList,
   validateOptionalField,
   validateRequiredField,
 } from './common'
@@ -28,6 +29,12 @@ export interface AccountDelete extends BaseTransaction {
    * information for the recipient of the deleted account's leftover XRP.
    */
   DestinationTag?: number
+  /**
+   * Credentials associated with sender of this transaction. The credentials included
+   * must not be expired. The list must not be empty when specified and cannot contain
+   * more than 8 credentials.
+   */
+  CredentialIDs?: string[]
 }
 
 /**
@@ -41,4 +48,11 @@ export function validateAccountDelete(tx: Record<string, unknown>): void {
 
   validateRequiredField(tx, 'Destination', isAccount)
   validateOptionalField(tx, 'DestinationTag', isNumber)
+
+  validateCredentialsList(
+    tx.CredentialIDs,
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- known from base check
+    tx.TransactionType as string,
+    true,
+  )
 }

package/src/models/transactions/clawback.ts

@@ -1,10 +1,13 @@
 import { ValidationError } from '../../errors'
-import { IssuedCurrencyAmount } from '../common'
+import { IssuedCurrencyAmount, MPTAmount } from '../common'
 
 import {
   BaseTransaction,
   validateBaseTransaction,
   isIssuedCurrency,
+  isMPTAmount,
+  isAccount,
+  validateOptionalField,
 } from './common'
 
 /**
@@ -15,15 +18,20 @@ export interface Clawback extends BaseTransaction {
   TransactionType: 'Clawback'
   /**
    * Indicates the AccountID that submitted this transaction. The account MUST
-   * be the issuer of the currency.
+   * be the issuer of the currency or MPT.
    */
   Account: string
   /**
-   * The amount of currency to deliver, and it must be non-XRP. The nested field
-   * names MUST be lower-case. The `issuer` field MUST be the holder's address,
+   * The amount of currency or MPT to clawback, and it must be non-XRP. The nested field
+   * 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
+  Amount: IssuedCurrencyAmount | MPTAmount
+  /**
+   * Indicates the AccountID that the issuer wants to clawback. This field is only valid for clawing back
+   * MPTs.
+   */
+  Holder?: string
 }
 
 /**
@@ -34,16 +42,29 @@ export interface Clawback extends BaseTransaction {
  */
 export function validateClawback(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
+  validateOptionalField(tx, 'Holder', isAccount)
 
   if (tx.Amount == null) {
     throw new ValidationError('Clawback: missing field Amount')
   }
 
-  if (!isIssuedCurrency(tx.Amount)) {
+  if (!isIssuedCurrency(tx.Amount) && !isMPTAmount(tx.Amount)) {
     throw new ValidationError('Clawback: invalid Amount')
   }
 
   if (isIssuedCurrency(tx.Amount) && tx.Account === tx.Amount.issuer) {
     throw new ValidationError('Clawback: invalid holder Account')
   }
+
+  if (isMPTAmount(tx.Amount) && tx.Account === tx.Holder) {
+    throw new ValidationError('Clawback: invalid holder Account')
+  }
+
+  if (isIssuedCurrency(tx.Amount) && tx.Holder) {
+    throw new ValidationError('Clawback: cannot have Holder for currency')
+  }
+
+  if (isMPTAmount(tx.Amount) && !tx.Holder) {
+    throw new ValidationError('Clawback: missing Holder')
+  }
 }

package/src/models/transactions/common.ts

@@ -1,18 +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,
   Memo,
   Signer,
   XChainBridge,
+  MPTAmount,
 } from '../common'
 import { onlyHasFields } from '../utils'
 
 const MEMO_SIZE = 3
+const MAX_CREDENTIALS_LIST_LENGTH = 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) {
@@ -59,6 +66,8 @@ const XRP_CURRENCY_SIZE = 1
 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'
@@ -119,6 +128,37 @@ 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
+ */
+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.
+ *
+ * @param input - The input to check the form and type of.
+ * @returns Whether the MPTAmount is properly formed.
+ */
+export function isMPTAmount(input: unknown): input is MPTAmount {
+  return (
+    isRecord(input) &&
+    Object.keys(input).length === MPTOKEN_SIZE &&
+    typeof input.value === 'string' &&
+    typeof input.mpt_issuance_id === 'string'
+  )
+}
+
 /**
  * Must be a valid account address
  */
@@ -144,7 +184,11 @@ export function isAccount(account: unknown): account is Account {
  * @returns Whether the Amount is properly formed.
  */
 export function isAmount(amount: unknown): amount is Amount {
-  return typeof amount === 'string' || isIssuedCurrency(amount)
+  return (
+    typeof amount === 'string' ||
+    isIssuedCurrency(amount) ||
+    isMPTAmount(amount)
+  )
 }
 
 /**
@@ -366,3 +410,97 @@ 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
+ * @throws Validation Error if the formatting is incorrect
+ */
+// eslint-disable-next-line max-lines-per-function -- separating logic further will add unnecessary complexity
+export function validateCredentialsList(
+  credentials: unknown,
+  transactionType: string,
+  isStringID: boolean,
+): void {
+  if (credentials == null) {
+    return
+  }
+  if (!Array.isArray(credentials)) {
+    throw new ValidationError(
+      `${transactionType}: Credentials must be an array`,
+    )
+  }
+  if (credentials.length > MAX_CREDENTIALS_LIST_LENGTH) {
+    throw new ValidationError(
+      `${transactionType}: Credentials length cannot exceed ${MAX_CREDENTIALS_LIST_LENGTH} 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`,
+    )
+  }
+}
+
+function containsDuplicates(objectList: object[]): boolean {
+  const objSet = new Set(objectList.map((obj) => JSON.stringify(obj)))
+  return objSet.size !== objectList.length
+}