xrpl 2.11.0 → 2.12.0

package/src/models/transactions/common.ts

@@ -1,10 +1,14 @@
-/* eslint-disable max-lines-per-function -- Necessary for validateBaseTransaction */
-/* eslint-disable complexity -- Necessary for validateBaseTransaction */
-/* eslint-disable max-statements -- Necessary for validateBaseTransaction */
 import { TRANSACTION_TYPES } from 'ripple-binary-codec'
 
 import { ValidationError } from '../../errors'
-import { Amount, Currency, IssuedCurrencyAmount, Memo, Signer } from '../common'
+import {
+  Amount,
+  Currency,
+  IssuedCurrencyAmount,
+  Memo,
+  Signer,
+  XChainBridge,
+} from '../common'
 import { onlyHasFields } from '../utils'
 
 const MEMO_SIZE = 3
@@ -53,11 +57,32 @@ function isSigner(obj: unknown): boolean {
 const XRP_CURRENCY_SIZE = 1
 const ISSUE_SIZE = 2
 const ISSUED_CURRENCY_SIZE = 3
+const XCHAIN_BRIDGE_SIZE = 4
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object'
 }
 
+/**
+ * Verify the form and type of a string at runtime.
+ *
+ * @param str - The object to check the form and type of.
+ * @returns Whether the string is properly formed.
+ */
+export function isString(str: unknown): str is string {
+  return typeof str === 'string'
+}
+
+/**
+ * Verify the form and type of a number at runtime.
+ *
+ * @param num - The object to check the form and type of.
+ * @returns Whether the number is properly formed.
+ */
+export function isNumber(num: unknown): num is number {
+  return typeof num === 'number'
+}
+
 /**
  * Verify the form and type of an IssuedCurrency at runtime.
  *
@@ -103,6 +128,73 @@ export function isAmount(amount: unknown): amount is Amount {
   return typeof amount === 'string' || isIssuedCurrency(amount)
 }
 
+/**
+ * Verify the form and type of an XChainBridge at runtime.
+ *
+ * @param input - The input to check the form and type of.
+ * @returns Whether the XChainBridge is properly formed.
+ */
+export function isXChainBridge(input: unknown): input is XChainBridge {
+  return (
+    isRecord(input) &&
+    Object.keys(input).length === XCHAIN_BRIDGE_SIZE &&
+    typeof input.LockingChainDoor === 'string' &&
+    isCurrency(input.LockingChainIssue) &&
+    typeof input.IssuingChainDoor === 'string' &&
+    isCurrency(input.IssuingChainIssue)
+  )
+}
+
+/* eslint-disable @typescript-eslint/restrict-template-expressions -- tx.TransactionType is checked before any calls */
+
+/**
+ * Verify the form and type of a required type for a transaction at runtime.
+ *
+ * @param tx - The transaction input to check the form and type of.
+ * @param paramName - The name of the transaction parameter.
+ * @param checkValidity - The function to use to check the type.
+ * @throws
+ */
+export function validateRequiredField(
+  tx: Record<string, unknown>,
+  paramName: string,
+  checkValidity: (inp: unknown) => boolean,
+): void {
+  if (tx[paramName] == null) {
+    throw new ValidationError(
+      `${tx.TransactionType}: missing field ${paramName}`,
+    )
+  }
+
+  if (!checkValidity(tx[paramName])) {
+    throw new ValidationError(
+      `${tx.TransactionType}: invalid field ${paramName}`,
+    )
+  }
+}
+
+/**
+ * Verify the form and type of an optional type for a transaction at runtime.
+ *
+ * @param tx - The transaction input to check the form and type of.
+ * @param paramName - The name of the transaction parameter.
+ * @param checkValidity - The function to use to check the type.
+ * @throws
+ */
+export function validateOptionalField(
+  tx: Record<string, unknown>,
+  paramName: string,
+  checkValidity: (inp: unknown) => boolean,
+): void {
+  if (tx[paramName] !== undefined && !checkValidity(tx[paramName])) {
+    throw new ValidationError(
+      `${tx.TransactionType}: invalid field ${paramName}`,
+    )
+  }
+}
+
+/* eslint-enable @typescript-eslint/restrict-template-expressions -- checked before */
+
 // eslint-disable-next-line @typescript-eslint/no-empty-interface -- no global flags right now, so this is fine
 export interface GlobalFlags {}
 
@@ -191,14 +283,6 @@ export interface BaseTransaction {
  * @throws When the common param is malformed.
  */
 export function validateBaseTransaction(common: Record<string, unknown>): void {
-  if (common.Account === undefined) {
-    throw new ValidationError('BaseTransaction: missing field Account')
-  }
-
-  if (typeof common.Account !== 'string') {
-    throw new ValidationError('BaseTransaction: Account not string')
-  }
-
   if (common.TransactionType === undefined) {
     throw new ValidationError('BaseTransaction: missing field TransactionType')
   }
@@ -211,27 +295,15 @@ export function validateBaseTransaction(common: Record<string, unknown>): void {
     throw new ValidationError('BaseTransaction: Unknown TransactionType')
   }
 
-  if (common.Fee !== undefined && typeof common.Fee !== 'string') {
-    throw new ValidationError('BaseTransaction: invalid Fee')
-  }
+  validateRequiredField(common, 'Account', isString)
 
-  if (common.Sequence !== undefined && typeof common.Sequence !== 'number') {
-    throw new ValidationError('BaseTransaction: invalid Sequence')
-  }
+  validateOptionalField(common, 'Fee', isString)
 
-  if (
-    common.AccountTxnID !== undefined &&
-    typeof common.AccountTxnID !== 'string'
-  ) {
-    throw new ValidationError('BaseTransaction: invalid AccountTxnID')
-  }
+  validateOptionalField(common, 'Sequence', isNumber)
 
-  if (
-    common.LastLedgerSequence !== undefined &&
-    typeof common.LastLedgerSequence !== 'number'
-  ) {
-    throw new ValidationError('BaseTransaction: invalid LastLedgerSequence')
-  }
+  validateOptionalField(common, 'AccountTxnID', isString)
+
+  validateOptionalField(common, 'LastLedgerSequence', isNumber)
 
   // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
   const memos = common.Memos as Array<{ Memo?: unknown }> | undefined
@@ -249,33 +321,15 @@ export function validateBaseTransaction(common: Record<string, unknown>): void {
     throw new ValidationError('BaseTransaction: invalid Signers')
   }
 
-  if (common.SourceTag !== undefined && typeof common.SourceTag !== 'number') {
-    throw new ValidationError('BaseTransaction: invalid SourceTag')
-  }
+  validateOptionalField(common, 'SourceTag', isNumber)
 
-  if (
-    common.SigningPubKey !== undefined &&
-    typeof common.SigningPubKey !== 'string'
-  ) {
-    throw new ValidationError('BaseTransaction: invalid SigningPubKey')
-  }
+  validateOptionalField(common, 'SigningPubKey', isString)
 
-  if (
-    common.TicketSequence !== undefined &&
-    typeof common.TicketSequence !== 'number'
-  ) {
-    throw new ValidationError('BaseTransaction: invalid TicketSequence')
-  }
+  validateOptionalField(common, 'TicketSequence', isNumber)
 
-  if (
-    common.TxnSignature !== undefined &&
-    typeof common.TxnSignature !== 'string'
-  ) {
-    throw new ValidationError('BaseTransaction: invalid TxnSignature')
-  }
-  if (common.NetworkID !== undefined && typeof common.NetworkID !== 'number') {
-    throw new ValidationError('BaseTransaction: invalid NetworkID')
-  }
+  validateOptionalField(common, 'TxnSignature', isString)
+
+  validateOptionalField(common, 'NetworkID', isNumber)
 }
 
 /**

package/src/models/transactions/depositPreauth.ts

@@ -1,4 +1,3 @@
-/* eslint-disable complexity -- Necessary for validateDepositPreauth */
 import { ValidationError } from '../../errors'
 
 import { BaseTransaction, validateBaseTransaction } from './common'

package/src/models/transactions/escrowCancel.ts

@@ -15,7 +15,7 @@ export interface EscrowCancel extends BaseTransaction {
    * Transaction sequence (or Ticket  number) of EscrowCreate transaction that.
    * created the escrow to cancel.
    */
-  OfferSequence: number
+  OfferSequence: number | string
 }
 
 /**
@@ -27,7 +27,7 @@ export interface EscrowCancel extends BaseTransaction {
 export function validateEscrowCancel(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
 
-  if (tx.Owner === undefined) {
+  if (tx.Owner == null) {
     throw new ValidationError('EscrowCancel: missing Owner')
   }
 
@@ -35,11 +35,15 @@ export function validateEscrowCancel(tx: Record<string, unknown>): void {
     throw new ValidationError('EscrowCancel: Owner must be a string')
   }
 
-  if (tx.OfferSequence === undefined) {
+  if (tx.OfferSequence == null) {
     throw new ValidationError('EscrowCancel: missing OfferSequence')
   }
 
-  if (typeof tx.OfferSequence !== 'number') {
+  if (
+    (typeof tx.OfferSequence !== 'number' &&
+      typeof tx.OfferSequence !== 'string') ||
+    Number.isNaN(Number(tx.OfferSequence))
+  ) {
     throw new ValidationError('EscrowCancel: OfferSequence must be a number')
   }
 }

package/src/models/transactions/escrowCreate.ts

@@ -1,4 +1,3 @@
-/* eslint-disable complexity -- Necessary for validateEscrowCreate */
 import { ValidationError } from '../../errors'
 
 import { BaseTransaction, validateBaseTransaction } from './common'

package/src/models/transactions/escrowFinish.ts

@@ -15,7 +15,7 @@ export interface EscrowFinish extends BaseTransaction {
    * Transaction sequence of EscrowCreate transaction that created the held.
    * payment to finish.
    */
-  OfferSequence: number
+  OfferSequence: number | string
   /**
    * Hex value matching the previously-supplied PREIMAGE-SHA-256.
    * crypto-condition of the held payment.
@@ -37,7 +37,7 @@ export interface EscrowFinish extends BaseTransaction {
 export function validateEscrowFinish(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
 
-  if (tx.Owner === undefined) {
+  if (tx.Owner == null) {
     throw new ValidationError('EscrowFinish: missing field Owner')
   }
 
@@ -45,11 +45,15 @@ export function validateEscrowFinish(tx: Record<string, unknown>): void {
     throw new ValidationError('EscrowFinish: Owner must be a string')
   }
 
-  if (tx.OfferSequence === undefined) {
+  if (tx.OfferSequence == null) {
     throw new ValidationError('EscrowFinish: missing field OfferSequence')
   }
 
-  if (typeof tx.OfferSequence !== 'number') {
+  if (
+    (typeof tx.OfferSequence !== 'number' &&
+      typeof tx.OfferSequence !== 'string') ||
+    Number.isNaN(Number(tx.OfferSequence))
+  ) {
     throw new ValidationError('EscrowFinish: OfferSequence must be a number')
   }
 

package/src/models/transactions/index.ts

@@ -25,6 +25,7 @@ export {
 export { CheckCancel } from './checkCancel'
 export { CheckCash } from './checkCash'
 export { CheckCreate } from './checkCreate'
+export { Clawback } from './clawback'
 export { DepositPreauth } from './depositPreauth'
 export { EscrowCancel } from './escrowCancel'
 export { EscrowCreate } from './escrowCreate'
@@ -63,4 +64,15 @@ export { SignerListSet } from './signerListSet'
 export { TicketCreate } from './ticketCreate'
 export { TrustSetFlagsInterface, TrustSetFlags, TrustSet } from './trustSet'
 export { UNLModify } from './UNLModify'
-export { Clawback } from './clawback'
+export { XChainAddAccountCreateAttestation } from './XChainAddAccountCreateAttestation'
+export { XChainAddClaimAttestation } from './XChainAddClaimAttestation'
+export { XChainClaim } from './XChainClaim'
+export { XChainCommit } from './XChainCommit'
+export { XChainCreateBridge } from './XChainCreateBridge'
+export { XChainCreateClaimID } from './XChainCreateClaimID'
+export { XChainAccountCreateCommit } from './XChainAccountCreateCommit'
+export {
+  XChainModifyBridge,
+  XChainModifyBridgeFlags,
+  XChainModifyBridgeFlagsInterface,
+} from './XChainModifyBridge'

package/src/models/transactions/offerCreate.ts

@@ -1,4 +1,3 @@
-/* eslint-disable complexity -- Necessary for validateOfferCreate */
 import { ValidationError } from '../../errors'
 import { Amount } from '../common'
 

package/src/models/transactions/payment.ts

@@ -1,4 +1,3 @@
-/* eslint-disable complexity -- Necessary for validatePayment */
 import { ValidationError } from '../../errors'
 import { Amount, Path } from '../common'
 import { isFlagEnabled } from '../utils'

package/src/models/transactions/paymentChannelClaim.ts

@@ -1,4 +1,3 @@
-/* eslint-disable complexity -- Necessary for validatePaymentChannelClaim */
 import { ValidationError } from '../../errors'
 
 import { BaseTransaction, GlobalFlags, validateBaseTransaction } from './common'

package/src/models/transactions/paymentChannelCreate.ts

@@ -1,4 +1,3 @@
-/* eslint-disable complexity -- Necessary for validatePaymentChannelCreate */
 import { ValidationError } from '../../errors'
 
 import { BaseTransaction, validateBaseTransaction } from './common'

package/src/models/transactions/signerListSet.ts

@@ -36,7 +36,6 @@ const HEX_WALLET_LOCATOR_REGEX = /^[0-9A-Fa-f]{64}$/u
  * @param tx - An SignerListSet Transaction.
  * @throws When the SignerListSet is Malformed.
  */
-// eslint-disable-next-line complexity -- validation can be complex
 export function validateSignerListSet(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
 

package/src/models/transactions/transaction.ts

@@ -1,4 +1,4 @@
-/* eslint-disable complexity -- verifies 19 tx types hence a lot of checks needed */
+/* eslint-disable max-lines -- need to work with a lot of transactions in a switch statement */
 /* eslint-disable max-lines-per-function -- need to work with a lot of Tx verifications */
 
 import { ValidationError } from '../../errors'
@@ -57,6 +57,32 @@ import { SetRegularKey, validateSetRegularKey } from './setRegularKey'
 import { SignerListSet, validateSignerListSet } from './signerListSet'
 import { TicketCreate, validateTicketCreate } from './ticketCreate'
 import { TrustSet, validateTrustSet } from './trustSet'
+import {
+  XChainAccountCreateCommit,
+  validateXChainAccountCreateCommit,
+} from './XChainAccountCreateCommit'
+import {
+  XChainAddAccountCreateAttestation,
+  validateXChainAddAccountCreateAttestation,
+} from './XChainAddAccountCreateAttestation'
+import {
+  XChainAddClaimAttestation,
+  validateXChainAddClaimAttestation,
+} from './XChainAddClaimAttestation'
+import { XChainClaim, validateXChainClaim } from './XChainClaim'
+import { XChainCommit, validateXChainCommit } from './XChainCommit'
+import {
+  XChainCreateBridge,
+  validateXChainCreateBridge,
+} from './XChainCreateBridge'
+import {
+  XChainCreateClaimID,
+  validateXChainCreateClaimID,
+} from './XChainCreateClaimID'
+import {
+  XChainModifyBridge,
+  validateXChainModifyBridge,
+} from './XChainModifyBridge'
 
 /**
  * @category Transaction Models
@@ -93,6 +119,14 @@ export type Transaction =
   | SignerListSet
   | TicketCreate
   | TrustSet
+  | XChainAddAccountCreateAttestation
+  | XChainAddClaimAttestation
+  | XChainClaim
+  | XChainCommit
+  | XChainCreateBridge
+  | XChainCreateClaimID
+  | XChainAccountCreateCommit
+  | XChainModifyBridge
 
 /**
  * @category Transaction Models
@@ -295,6 +329,38 @@ export function validate(transaction: Record<string, unknown>): void {
       validateTrustSet(tx)
       break
 
+    case 'XChainAddAccountCreateAttestation':
+      validateXChainAddAccountCreateAttestation(tx)
+      break
+
+    case 'XChainAddClaimAttestation':
+      validateXChainAddClaimAttestation(tx)
+      break
+
+    case 'XChainClaim':
+      validateXChainClaim(tx)
+      break
+
+    case 'XChainCommit':
+      validateXChainCommit(tx)
+      break
+
+    case 'XChainCreateBridge':
+      validateXChainCreateBridge(tx)
+      break
+
+    case 'XChainCreateClaimID':
+      validateXChainCreateClaimID(tx)
+      break
+
+    case 'XChainAccountCreateCommit':
+      validateXChainAccountCreateCommit(tx)
+      break
+
+    case 'XChainModifyBridge':
+      validateXChainModifyBridge(tx)
+      break
+
     default:
       throw new ValidationError(
         `Invalid field TransactionType: ${tx.TransactionType}`,

package/src/models/utils/flags.ts

@@ -15,6 +15,7 @@ import { PaymentFlags } from '../transactions/payment'
 import { PaymentChannelClaimFlags } from '../transactions/paymentChannelClaim'
 import type { Transaction } from '../transactions/transaction'
 import { TrustSetFlags } from '../transactions/trustSet'
+import { XChainModifyBridgeFlags } from '../transactions/XChainModifyBridge'
 
 import { isFlagEnabled } from '.'
 
@@ -78,6 +79,9 @@ export function setTransactionFlagsToNumber(tx: Transaction): void {
     case 'TrustSet':
       tx.Flags = convertFlagsToNumber(tx.Flags, TrustSetFlags)
       return
+    case 'XChainModifyBridge':
+      tx.Flags = convertFlagsToNumber(tx.Flags, XChainModifyBridgeFlags)
+      return
     default:
       tx.Flags = 0
   }

package/src/sugar/autofill.ts

@@ -176,8 +176,6 @@ function txNeedsNetworkID(client: Client): boolean {
     client.networkID !== undefined &&
     client.networkID > RESTRICTED_NETWORKS
   ) {
-    // TODO: remove the buildVersion logic when 1.11.0 is out and widely used.
-    // Issue: https://github.com/XRPLF/xrpl.js/issues/2339
     if (
       (client.buildVersion &&
         isNotLaterRippledVersion(

package/src/utils/getXChainClaimID.ts

@@ -0,0 +1,64 @@
+import { decode } from 'ripple-binary-codec'
+
+import {
+  CreatedNode,
+  isCreatedNode,
+  TransactionMetadata,
+} from '../models/transactions/metadata'
+
+/**
+ * Ensures that the metadata is in a deserialized format to parse.
+ *
+ * @param meta - the metadata from a `tx` method call. Can be in json format or binary format.
+ * @returns the metadata in a deserialized format.
+ */
+function ensureDecodedMeta(
+  meta: TransactionMetadata | string,
+): TransactionMetadata {
+  if (typeof meta === 'string') {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Meta is either metadata or serialized metadata.
+    return decode(meta) as unknown as TransactionMetadata
+  }
+  return meta
+}
+
+/**
+ * Gets the XChainClaimID value from the metadata of an `XChainCreateClaimID` transaction.
+ *
+ * @param meta - Metadata from the response to submitting and waiting for an XChainCreateClaimID transaction
+ *               or from a `tx` method call.
+ * @returns The XChainClaimID for the minted NFT.
+ * @throws if meta is not TransactionMetadata.
+ */
+export default function getXChainClaimID(
+  meta: TransactionMetadata | string | undefined,
+): string | undefined {
+  if (typeof meta !== 'string' && meta?.AffectedNodes === undefined) {
+    throw new TypeError(`Unable to parse the parameter given to getXChainClaimID.
+      'meta' must be the metadata from an XChainCreateClaimID transaction. Received ${JSON.stringify(
+        meta,
+      )} instead.`)
+  }
+
+  const decodedMeta = ensureDecodedMeta(meta)
+
+  if (!decodedMeta.TransactionResult) {
+    throw new TypeError(
+      'Cannot get XChainClaimID from un-validated transaction',
+    )
+  }
+
+  if (decodedMeta.TransactionResult !== 'tesSUCCESS') {
+    return undefined
+  }
+
+  const createdNode = decodedMeta.AffectedNodes.find(
+    (node) =>
+      isCreatedNode(node) &&
+      node.CreatedNode.LedgerEntryType === 'XChainOwnedClaimID',
+  )
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- necessary here
+  return (createdNode as CreatedNode).CreatedNode.NewFields
+    .XChainClaimID as string
+}

package/src/utils/index.ts

@@ -25,6 +25,7 @@ import { Transaction } from '../models/transactions/transaction'
 import { deriveKeypair, deriveAddress, deriveXAddress } from './derive'
 import getBalanceChanges from './getBalanceChanges'
 import getNFTokenID from './getNFTokenID'
+import getXChainClaimID from './getXChainClaimID'
 import {
   hashSignedTx,
   hashTx,
@@ -220,4 +221,5 @@ export {
   encodeForSigningClaim,
   getNFTokenID,
   parseNFTokenID,
+  getXChainClaimID,
 }

package/src/utils/signPaymentChannelClaim.ts

@@ -7,19 +7,19 @@ import { xrpToDrops } from './xrpConversion'
  * Sign a payment channel claim.
  *
  * @param channel - Channel identifier specified by the paymentChannelClaim.
- * @param amount - Amount specified by the paymentChannelClaim.
+ * @param xrpAmount - XRP Amount specified by the paymentChannelClaim.
  * @param privateKey - Private Key to sign paymentChannelClaim with.
  * @returns True if the channel is valid.
  * @category Utilities
  */
 function signPaymentChannelClaim(
   channel: string,
-  amount: string,
+  xrpAmount: string,
   privateKey: string,
 ): string {
   const signingData = encodeForSigningClaim({
     channel,
-    amount: xrpToDrops(amount),
+    amount: xrpToDrops(xrpAmount),
   })
   return sign(signingData, privateKey)
 }

package/src/utils/verifyPaymentChannelClaim.ts

@@ -7,7 +7,7 @@ import { xrpToDrops } from './xrpConversion'
  * Verify the signature of a payment channel claim.
  *
  * @param channel - Channel identifier specified by the paymentChannelClaim.
- * @param amount - Amount specified by the paymentChannelClaim.
+ * @param xrpAmount - XRP Amount specified by the paymentChannelClaim.
  * @param signature - Signature produced from signing paymentChannelClaim.
  * @param publicKey - Public key that signed the paymentChannelClaim.
  * @returns True if the channel is valid.
@@ -16,13 +16,13 @@ import { xrpToDrops } from './xrpConversion'
 // eslint-disable-next-line max-params -- Needs 4 params
 function verifyPaymentChannelClaim(
   channel: string,
-  amount: string,
+  xrpAmount: string,
   signature: string,
   publicKey: string,
 ): boolean {
   const signingData = encodeForSigningClaim({
     channel,
-    amount: xrpToDrops(amount),
+    amount: xrpToDrops(xrpAmount),
   })
   return verify(signingData, signature, publicKey)
 }