xrpl 2.14.1 → 2.14.2

package/src/models/transactions/AMMDeposit.ts

@@ -21,6 +21,7 @@ export enum AMMDepositFlags {
   tfTwoAsset = 0x00100000,
   tfOneAssetLPToken = 0x00200000,
   tfLimitLPToken = 0x00400000,
+  tfTwoAssetIfEmpty = 0x00800000,
 }
 
 export interface AMMDepositFlagsInterface extends GlobalFlags {
@@ -29,6 +30,7 @@ export interface AMMDepositFlagsInterface extends GlobalFlags {
   tfTwoAsset?: boolean
   tfOneAssetLPToken?: boolean
   tfLimitLPToken?: boolean
+  tfTwoAssetIfEmpty?: boolean
 }
 
 /**

package/src/models/transactions/CredentialAccept.ts

@@ -0,0 +1,44 @@
+import {
+  BaseTransaction,
+  isString,
+  validateBaseTransaction,
+  validateCredentialType,
+  validateRequiredField,
+} from './common'
+
+/**
+ * Accepts a credential issued to the Account (i.e. the Account is the Subject of the Credential object).
+ * Credentials are represented in hex. Whilst they are allowed a maximum length of 64
+ * bytes, every byte requires 2 hex characters for representation.
+ * The credential is not considered valid until it has been transferred/accepted.
+ *
+ * @category Transaction Models
+ * */
+export interface CredentialAccept extends BaseTransaction {
+  TransactionType: 'CredentialAccept'
+
+  /** The subject of the credential. */
+  Account: string
+
+  /** The issuer of the credential. */
+  Issuer: string
+
+  /** A hex-encoded value to identify the type of credential from the issuer. */
+  CredentialType: string
+}
+
+/**
+ * Verify the form and type of a CredentialAccept at runtime.
+ *
+ * @param tx - A CredentialAccept Transaction.
+ * @throws When the CredentialAccept is Malformed.
+ */
+export function validateCredentialAccept(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'Account', isString)
+
+  validateRequiredField(tx, 'Issuer', isString)
+
+  validateCredentialType(tx)
+}

package/src/models/transactions/CredentialCreate.ts

@@ -0,0 +1,81 @@
+import { HEX_REGEX } from '@xrplf/isomorphic/utils'
+
+import { ValidationError } from '../../errors'
+
+import {
+  BaseTransaction,
+  isNumber,
+  isString,
+  validateBaseTransaction,
+  validateCredentialType,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
+
+const MAX_URI_LENGTH = 256
+
+/**
+ * Creates a Credential object. It must be sent by the issuer.
+ *
+ * @category Transaction Models
+ * */
+export interface CredentialCreate extends BaseTransaction {
+  TransactionType: 'CredentialCreate'
+
+  /** The issuer of the credential. */
+  Account: string
+
+  /** The subject of the credential. */
+  Subject: string
+
+  /** A hex-encoded value to identify the type of credential from the issuer. */
+  CredentialType: string
+
+  /** Credential expiration. */
+  Expiration?: number
+
+  /** Additional data about the credential (such as a link to the VC document). */
+  URI?: string
+}
+
+/**
+ * Verify the form and type of a CredentialCreate at runtime.
+ *
+ * @param tx - A CredentialCreate Transaction.
+ * @throws When the CredentialCreate is Malformed.
+ */
+export function validateCredentialCreate(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'Account', isString)
+
+  validateRequiredField(tx, 'Subject', isString)
+
+  validateCredentialType(tx)
+
+  validateOptionalField(tx, 'Expiration', isNumber)
+
+  validateURI(tx.URI)
+}
+
+function validateURI(URI: unknown): void {
+  if (URI === undefined) {
+    return
+  }
+
+  if (typeof URI !== 'string') {
+    throw new ValidationError('CredentialCreate: invalid field URI')
+  }
+
+  if (URI.length === 0) {
+    throw new ValidationError('CredentialCreate: URI cannot be an empty string')
+  } else if (URI.length > MAX_URI_LENGTH) {
+    throw new ValidationError(
+      `CredentialCreate: URI length must be <= ${MAX_URI_LENGTH}`,
+    )
+  }
+
+  if (!HEX_REGEX.test(URI)) {
+    throw new ValidationError('CredentialCreate: URI must be encoded in hex')
+  }
+}

package/src/models/transactions/CredentialDelete.ts

@@ -0,0 +1,55 @@
+import { ValidationError } from '../../errors'
+
+import {
+  BaseTransaction,
+  isString,
+  validateBaseTransaction,
+  validateCredentialType,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
+
+/**
+ * Deletes a Credential object.
+ *
+ * @category Transaction Models
+ * */
+export interface CredentialDelete extends BaseTransaction {
+  TransactionType: 'CredentialDelete'
+
+  /** The transaction submitter. */
+  Account: string
+
+  /** A hex-encoded value to identify the type of credential from the issuer. */
+  CredentialType: string
+
+  /** The person that the credential is for. If omitted, Account is assumed to be the subject. */
+  Subject?: string
+
+  /** The issuer of the credential. If omitted, Account is assumed to be the issuer. */
+  Issuer?: string
+}
+
+/**
+ * Verify the form and type of a CredentialDelete at runtime.
+ *
+ * @param tx - A CredentialDelete Transaction.
+ * @throws When the CredentialDelete is Malformed.
+ */
+export function validateCredentialDelete(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (!tx.Subject && !tx.Issuer) {
+    throw new ValidationError(
+      'CredentialDelete: either `Issuer` or `Subject` must be provided',
+    )
+  }
+
+  validateRequiredField(tx, 'Account', isString)
+
+  validateCredentialType(tx)
+
+  validateOptionalField(tx, 'Subject', isString)
+
+  validateOptionalField(tx, 'Issuer', isString)
+}

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

@@ -6,6 +6,7 @@ import {
   parseAmountValue,
   validateBaseTransaction,
 } from './common'
+import type { TransactionMetadataBase } from './metadata'
 
 /**
  *  The NFTokenOfferAccept transaction is used to accept offers
@@ -64,6 +65,11 @@ export interface NFTokenAcceptOffer extends BaseTransaction {
   NFTokenBrokerFee?: Amount
 }
 
+export interface NFTokenAcceptOfferMetadata extends TransactionMetadataBase {
+  // rippled 1.11.0 or later
+  nftoken_id?: string
+}
+
 function validateNFTokenBrokerFee(tx: Record<string, unknown>): void {
   const value = parseAmountValue(tx.NFTokenBrokerFee)
   if (Number.isNaN(value)) {

package/src/models/transactions/NFTokenCancelOffer.ts

@@ -1,6 +1,7 @@
 import { ValidationError } from '../../errors'
 
 import { BaseTransaction, validateBaseTransaction } from './common'
+import type { TransactionMetadataBase } from './metadata'
 
 /**
  * The NFTokenCancelOffer transaction deletes existing NFTokenOffer objects.
@@ -26,6 +27,11 @@ export interface NFTokenCancelOffer extends BaseTransaction {
   NFTokenOffers: string[]
 }
 
+export interface NFTokenCancelOfferMetadata extends TransactionMetadataBase {
+  // rippled 1.11.0  or  later
+  nftoken_ids?: string[]
+}
+
 /**
  * Verify the form and type of an NFTokenCancelOffer at runtime.
  *

package/src/models/transactions/NFTokenCreateOffer.ts

@@ -12,6 +12,7 @@ import {
   validateOptionalField,
   Account,
 } from './common'
+import type { TransactionMetadataBase } from './metadata'
 
 /**
  * Transaction Flags for an NFTokenCreateOffer Transaction.
@@ -86,6 +87,11 @@ export interface NFTokenCreateOffer extends BaseTransaction {
   Flags?: number | NFTokenCreateOfferFlagsInterface
 }
 
+export interface NFTokenCreateOfferMetadata extends TransactionMetadataBase {
+  // rippled 1.11.0 or later
+  offer_id?: string
+}
+
 function validateNFTokenSellOfferCases(tx: Record<string, unknown>): void {
   if (tx.Owner != null) {
     throw new ValidationError(

package/src/models/transactions/NFTokenMint.ts

@@ -9,6 +9,7 @@ import {
   validateBaseTransaction,
   validateOptionalField,
 } from './common'
+import type { TransactionMetadataBase } from './metadata'
 
 /**
  * Transaction Flags for an NFTokenMint Transaction.
@@ -37,6 +38,10 @@ export enum NFTokenMintFlags {
    * issuer.
    */
   tfTransferable = 0x00000008,
+  /**
+   * If set, indicates that this NFT's URI can be modified.
+   */
+  tfMutable = 0x00000010,
 }
 
 /**
@@ -50,6 +55,7 @@ export interface NFTokenMintFlagsInterface extends GlobalFlags {
   tfOnlyXRP?: boolean
   tfTrustLine?: boolean
   tfTransferable?: boolean
+  tfMutable?: boolean
 }
 
 /**
@@ -101,6 +107,11 @@ export interface NFTokenMint extends BaseTransaction {
   Flags?: number | NFTokenMintFlagsInterface
 }
 
+export interface NFTokenMintMetadata extends TransactionMetadataBase {
+  // rippled 1.11.0 or later
+  nftoken_id?: string
+}
+
 /**
  * Verify the form and type of an NFTokenMint at runtime.
  *