xrpl 4.0.1-mpt-beta → 4.1.0

package/src/models/transactions/common.ts

@@ -1,9 +1,12 @@
+/* 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,
@@ -14,6 +17,9 @@ import {
 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) {
@@ -61,6 +67,7 @@ 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'
@@ -121,6 +128,22 @@ 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.
  *
@@ -387,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
+}

package/src/models/transactions/depositPreauth.ts

@@ -1,6 +1,11 @@
 import { ValidationError } from '../../errors'
+import { AuthorizeCredential } from '../common'
 
-import { BaseTransaction, validateBaseTransaction } from './common'
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  validateCredentialsList,
+} from './common'
 
 /**
  * A DepositPreauth transaction gives another account pre-approval to deliver
@@ -18,6 +23,16 @@ export interface DepositPreauth extends BaseTransaction {
    * revoked.
    */
   Unauthorize?: string
+
+  /**
+   * The credential(s) to preauthorize.
+   */
+  AuthorizeCredentials?: AuthorizeCredential[]
+
+  /**
+   * The credential(s) whose preauthorization should be revoked.
+   */
+  UnauthorizeCredentials?: AuthorizeCredential[]
 }
 
 /**
@@ -29,17 +44,7 @@ export interface DepositPreauth extends BaseTransaction {
 export function validateDepositPreauth(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
 
-  if (tx.Authorize !== undefined && tx.Unauthorize !== undefined) {
-    throw new ValidationError(
-      "DepositPreauth: can't provide both Authorize and Unauthorize fields",
-    )
-  }
-
-  if (tx.Authorize === undefined && tx.Unauthorize === undefined) {
-    throw new ValidationError(
-      'DepositPreauth: must provide either Authorize or Unauthorize field',
-    )
-  }
+  validateSingleAuthorizationFieldProvided(tx)
 
   if (tx.Authorize !== undefined) {
     if (typeof tx.Authorize !== 'string') {
@@ -51,9 +56,7 @@ export function validateDepositPreauth(tx: Record<string, unknown>): void {
         "DepositPreauth: Account can't preauthorize its own address",
       )
     }
-  }
-
-  if (tx.Unauthorize !== undefined) {
+  } else if (tx.Unauthorize !== undefined) {
     if (typeof tx.Unauthorize !== 'string') {
       throw new ValidationError('DepositPreauth: Unauthorize must be a string')
     }
@@ -63,5 +66,38 @@ export function validateDepositPreauth(tx: Record<string, unknown>): void {
         "DepositPreauth: Account can't unauthorize its own address",
       )
     }
+  } 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,
+      false,
+    )
+  } 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,
+      false,
+    )
+  }
+}
+
+// Boolean logic to ensure exactly one of 4 inputs was provided
+function validateSingleAuthorizationFieldProvided(
+  tx: Record<string, unknown>,
+): void {
+  const fields = [
+    'Authorize',
+    'Unauthorize',
+    'AuthorizeCredentials',
+    'UnauthorizeCredentials',
+  ]
+  const countProvided = fields.filter((key) => tx[key] !== undefined).length
+
+  if (countProvided !== 1) {
+    throw new ValidationError(
+      'DepositPreauth: Requires exactly one field of the following: Authorize, Unauthorize, AuthorizeCredentials, UnauthorizeCredentials.',
+    )
   }
 }

package/src/models/transactions/escrowFinish.ts

@@ -5,6 +5,7 @@ import {
   BaseTransaction,
   isAccount,
   validateBaseTransaction,
+  validateCredentialsList,
   validateRequiredField,
 } from './common'
 
@@ -32,6 +33,10 @@ export interface EscrowFinish extends BaseTransaction {
    * the held payment's Condition.
    */
   Fulfillment?: string
+  /** Credentials associated with the sender of this transaction.
+   * The credentials included must not be expired.
+   */
+  CredentialIDs?: string[]
 }
 
 /**
@@ -45,6 +50,13 @@ export function validateEscrowFinish(tx: Record<string, unknown>): void {
 
   validateRequiredField(tx, 'Owner', isAccount)
 
+  validateCredentialsList(
+    tx.CredentialIDs,
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- known from base check
+    tx.TransactionType as string,
+    true,
+  )
+
   if (tx.OfferSequence == null) {
     throw new ValidationError('EscrowFinish: missing field OfferSequence')
   }

package/src/models/transactions/index.ts

@@ -32,6 +32,9 @@ export { CheckCancel } from './checkCancel'
 export { CheckCash } from './checkCash'
 export { CheckCreate } from './checkCreate'
 export { Clawback } from './clawback'
+export { CredentialAccept } from './CredentialAccept'
+export { CredentialCreate } from './CredentialCreate'
+export { CredentialDelete } from './CredentialDelete'
 export { DIDDelete } from './DIDDelete'
 export { DIDSet } from './DIDSet'
 export { DepositPreauth } from './depositPreauth'

package/src/models/transactions/metadata.ts

@@ -1,6 +1,10 @@
 import { Amount, MPTAmount } from '../common'
 
 import { BaseTransaction } from './common'
+import {
+  MPTokenIssuanceCreate,
+  MPTokenIssuanceCreateMetadata,
+} from './MPTokenIssuanceCreate'
 import {
   NFTokenAcceptOffer,
   NFTokenAcceptOfferMetadata,
@@ -14,10 +18,6 @@ import {
   NFTokenCreateOfferMetadata,
 } from './NFTokenCreateOffer'
 import { NFTokenMint, NFTokenMintMetadata } from './NFTokenMint'
-import {
-  MPTokenIssuanceCreate,
-  MPTokenIssuanceCreateMetadata,
-} from './MPTokenIssuanceCreate'
 import { Payment, PaymentMetadata } from './payment'
 import type { Transaction } from './transaction'
 

package/src/models/transactions/payment.ts

@@ -12,6 +12,7 @@ import {
   validateOptionalField,
   isNumber,
   Account,
+  validateCredentialsList,
 } from './common'
 import type { TransactionMetadataBase } from './metadata'
 
@@ -142,13 +143,18 @@ export interface Payment extends BaseTransaction {
    * cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP
    * Payments.
    */
-  SendMax?: Amount
+  SendMax?: Amount | MPTAmount
   /**
    * Minimum amount of destination currency this transaction should deliver.
    * Only valid if this is a partial payment. For non-XRP amounts, the nested
    * field names are lower-case.
    */
-  DeliverMin?: Amount
+  DeliverMin?: Amount | MPTAmount
+  /**
+   * Credentials associated with the sender of this transaction.
+   * The credentials included must not be expired.
+   */
+  CredentialIDs?: string[]
   Flags?: number | PaymentFlagsInterface
 }
 
@@ -177,6 +183,13 @@ export function validatePayment(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,
+  )
+
   if (tx.InvoiceID !== undefined && typeof tx.InvoiceID !== 'string') {
     throw new ValidationError('PaymentTransaction: InvoiceID must be a string')
   }

package/src/models/transactions/paymentChannelClaim.ts

@@ -1,6 +1,11 @@
 import { ValidationError } from '../../errors'
 
-import { BaseTransaction, GlobalFlags, validateBaseTransaction } from './common'
+import {
+  BaseTransaction,
+  GlobalFlags,
+  validateBaseTransaction,
+  validateCredentialsList,
+} from './common'
 
 /**
  * Enum representing values for PaymentChannelClaim transaction flags.
@@ -127,6 +132,11 @@ export interface PaymentChannelClaim extends BaseTransaction {
    * field is omitted.
    */
   PublicKey?: string
+  /**
+   * Credentials associated with the sender of this transaction.
+   * The credentials included must not be expired.
+   */
+  CredentialIDs?: string[]
 }
 
 /**
@@ -138,6 +148,13 @@ export interface PaymentChannelClaim extends BaseTransaction {
 export function validatePaymentChannelClaim(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
 
+  validateCredentialsList(
+    tx.CredentialIDs,
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- known from base check
+    tx.TransactionType as string,
+    true,
+  )
+
   if (tx.Channel === undefined) {
     throw new ValidationError('PaymentChannelClaim: missing Channel')
   }

package/src/models/transactions/transaction.ts

@@ -19,6 +19,9 @@ import { CheckCash, validateCheckCash } from './checkCash'
 import { CheckCreate, validateCheckCreate } from './checkCreate'
 import { Clawback, validateClawback } from './clawback'
 import { BaseTransaction, isIssuedCurrency } from './common'
+import { CredentialAccept, validateCredentialAccept } from './CredentialAccept'
+import { CredentialCreate, validateCredentialCreate } from './CredentialCreate'
+import { CredentialDelete, validateCredentialDelete } from './CredentialDelete'
 import { DepositPreauth, validateDepositPreauth } from './depositPreauth'
 import { DIDDelete, validateDIDDelete } from './DIDDelete'
 import { DIDSet, validateDIDSet } from './DIDSet'
@@ -27,6 +30,19 @@ import { EscrowCancel, validateEscrowCancel } from './escrowCancel'
 import { EscrowCreate, validateEscrowCreate } from './escrowCreate'
 import { EscrowFinish, validateEscrowFinish } from './escrowFinish'
 import { TransactionMetadata } from './metadata'
+import { MPTokenAuthorize, validateMPTokenAuthorize } from './MPTokenAuthorize'
+import {
+  MPTokenIssuanceCreate,
+  validateMPTokenIssuanceCreate,
+} from './MPTokenIssuanceCreate'
+import {
+  MPTokenIssuanceDestroy,
+  validateMPTokenIssuanceDestroy,
+} from './MPTokenIssuanceDestroy'
+import {
+  MPTokenIssuanceSet,
+  validateMPTokenIssuanceSet,
+} from './MPTokenIssuanceSet'
 import {
   NFTokenAcceptOffer,
   validateNFTokenAcceptOffer,
@@ -90,19 +106,6 @@ import {
   XChainModifyBridge,
   validateXChainModifyBridge,
 } from './XChainModifyBridge'
-import { MPTokenAuthorize, validateMPTokenAuthorize } from './MPTokenAuthorize'
-import {
-  MPTokenIssuanceCreate,
-  validateMPTokenIssuanceCreate,
-} from './MPTokenIssuanceCreate'
-import {
-  MPTokenIssuanceDestroy,
-  validateMPTokenIssuanceDestroy,
-} from './MPTokenIssuanceDestroy'
-import {
-  MPTokenIssuanceSet,
-  validateMPTokenIssuanceSet,
-} from './MPTokenIssuanceSet'
 
 /**
  * Transactions that can be submitted by clients
@@ -122,6 +125,9 @@ export type SubmittableTransaction =
   | CheckCash
   | CheckCreate
   | Clawback
+  | CredentialAccept
+  | CredentialCreate
+  | CredentialDelete
   | DIDDelete
   | DIDSet
   | DepositPreauth
@@ -299,6 +305,18 @@ export function validate(transaction: Record<string, unknown>): void {
       validateClawback(tx)
       break
 
+    case 'CredentialAccept':
+      validateCredentialAccept(tx)
+      break
+
+    case 'CredentialCreate':
+      validateCredentialCreate(tx)
+      break
+
+    case 'CredentialDelete':
+      validateCredentialDelete(tx)
+      break
+
     case 'DIDDelete':
       validateDIDDelete(tx)
       break

package/src/models/utils/flags.ts

@@ -9,6 +9,9 @@ import { AccountSetTfFlags } from '../transactions/accountSet'
 import { AMMDepositFlags } from '../transactions/AMMDeposit'
 import { AMMWithdrawFlags } from '../transactions/AMMWithdraw'
 import { GlobalFlags } from '../transactions/common'
+import { MPTokenAuthorizeFlags } from '../transactions/MPTokenAuthorize'
+import { MPTokenIssuanceCreateFlags } from '../transactions/MPTokenIssuanceCreate'
+import { MPTokenIssuanceSetFlags } from '../transactions/MPTokenIssuanceSet'
 import { NFTokenCreateOfferFlags } from '../transactions/NFTokenCreateOffer'
 import { NFTokenMintFlags } from '../transactions/NFTokenMint'
 import { OfferCreateFlags } from '../transactions/offerCreate'
@@ -17,9 +20,6 @@ import { PaymentChannelClaimFlags } from '../transactions/paymentChannelClaim'
 import type { Transaction } from '../transactions/transaction'
 import { TrustSetFlags } from '../transactions/trustSet'
 import { XChainModifyBridgeFlags } from '../transactions/XChainModifyBridge'
-import { MPTokenAuthorizeFlags } from '../transactions/MPTokenAuthorize'
-import { MPTokenIssuanceCreateFlags } from '../transactions/MPTokenIssuanceCreate'
-import { MPTokenIssuanceSetFlags } from '../transactions/MPTokenIssuanceSet'
 
 import { isFlagEnabled } from '.'
 

package/src/models/utils/index.ts

@@ -1,4 +1,5 @@
 const HEX_REGEX = /^[0-9A-Fa-f]+$/u
+export const INTEGER_SANITY_CHECK = /^[0-9]+$/u
 
 /**
  * Verify that all fields of an object are in fields.

package/src/utils/index.ts

@@ -66,7 +66,6 @@ import {
 } from './timeConversion'
 import verifyPaymentChannelClaim from './verifyPaymentChannelClaim'
 import { xrpToDrops, dropsToXrp } from './xrpConversion'
-import { mptUint64ToHex } from './mptConversion'
 
 /**
  * Check if a secret is valid.
@@ -230,5 +229,4 @@ export {
   getNFTokenID,
   parseNFTokenID,
   getXChainClaimID,
-  mptUint64ToHex,
 }