xrpl 2.12.0 → 3.0.0-beta.0

package/src/models/transactions/escrowFinish.ts

@@ -1,6 +1,12 @@
 import { ValidationError } from '../../errors'
 
-import { BaseTransaction, validateBaseTransaction } from './common'
+import {
+  Account,
+  BaseTransaction,
+  isAccount,
+  validateBaseTransaction,
+  validateRequiredField,
+} from './common'
 
 /**
  * Deliver XRP from a held payment to the recipient.
@@ -10,7 +16,7 @@ import { BaseTransaction, validateBaseTransaction } from './common'
 export interface EscrowFinish extends BaseTransaction {
   TransactionType: 'EscrowFinish'
   /** Address of the source account that funded the held payment. */
-  Owner: string
+  Owner: Account
   /**
    * Transaction sequence of EscrowCreate transaction that created the held.
    * payment to finish.
@@ -37,13 +43,7 @@ export interface EscrowFinish extends BaseTransaction {
 export function validateEscrowFinish(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
 
-  if (tx.Owner == null) {
-    throw new ValidationError('EscrowFinish: missing field Owner')
-  }
-
-  if (typeof tx.Owner !== 'string') {
-    throw new ValidationError('EscrowFinish: Owner must be a string')
-  }
+  validateRequiredField(tx, 'Owner', isAccount)
 
   if (tx.OfferSequence == null) {
     throw new ValidationError('EscrowFinish: missing field OfferSequence')

package/src/models/transactions/index.ts

@@ -1,5 +1,10 @@
 export { BaseTransaction } from './common'
-export { validate, TransactionAndMetadata, Transaction } from './transaction'
+export {
+  validate,
+  PseudoTransaction,
+  TransactionAndMetadata,
+  Transaction,
+} from './transaction'
 export * from './metadata'
 export {
   AccountSetAsfFlags,

package/src/models/transactions/metadata.ts

@@ -1,5 +1,22 @@
 import { Amount } from '../common'
 
+import { BaseTransaction } from './common'
+import {
+  NFTokenAcceptOffer,
+  NFTokenAcceptOfferMetadata,
+} from './NFTokenAcceptOffer'
+import {
+  NFTokenCancelOffer,
+  NFTokenCancelOfferMetadata,
+} from './NFTokenCancelOffer'
+import {
+  NFTokenCreateOffer,
+  NFTokenCreateOfferMetadata,
+} from './NFTokenCreateOffer'
+import { NFTokenMint, NFTokenMintMetadata } from './NFTokenMint'
+import { Payment, PaymentMetadata } from './payment'
+import type { Transaction } from './transaction'
+
 export interface CreatedNode {
   CreatedNode: {
     LedgerEntryType: string
@@ -59,7 +76,7 @@ export function isDeletedNode(node: Node): node is DeletedNode {
   return Object.prototype.hasOwnProperty.call(node, `DeletedNode`)
 }
 
-export interface TransactionMetadata {
+export interface TransactionMetadataBase {
   AffectedNodes: Node[]
   DeliveredAmount?: Amount
   // "unavailable" possible for transactions before 2014-01-20
@@ -67,3 +84,16 @@ export interface TransactionMetadata {
   TransactionIndex: number
   TransactionResult: string
 }
+
+export type TransactionMetadata<T extends BaseTransaction = Transaction> =
+  T extends Payment
+    ? PaymentMetadata
+    : T extends NFTokenMint
+    ? NFTokenMintMetadata
+    : T extends NFTokenCreateOffer
+    ? NFTokenCreateOfferMetadata
+    : T extends NFTokenAcceptOffer
+    ? NFTokenAcceptOfferMetadata
+    : T extends NFTokenCancelOffer
+    ? NFTokenCancelOfferMetadata
+    : TransactionMetadataBase

package/src/models/transactions/payment.ts

@@ -7,7 +7,13 @@ import {
   isAmount,
   GlobalFlags,
   validateBaseTransaction,
+  isAccount,
+  validateRequiredField,
+  validateOptionalField,
+  isNumber,
+  Account,
 } from './common'
+import type { TransactionMetadataBase } from './metadata'
 
 /**
  * Enum representing values for Payment Transaction Flags.
@@ -112,7 +118,7 @@ export interface Payment extends BaseTransaction {
    */
   Amount: Amount
   /** The unique address of the account receiving the payment. */
-  Destination: string
+  Destination: Account
   /**
    * Arbitrary tag that identifies the reason for the payment to the
    * destination, or a hosted recipient to pay.
@@ -146,6 +152,11 @@ export interface Payment extends BaseTransaction {
   Flags?: number | PaymentFlagsInterface
 }
 
+export interface PaymentMetadata extends TransactionMetadataBase {
+  DeliveredAmount?: Amount
+  delivered_amount?: Amount | 'unavailable'
+}
+
 /**
  * Verify the form and type of a Payment at runtime.
  *
@@ -163,19 +174,8 @@ export function validatePayment(tx: Record<string, unknown>): void {
     throw new ValidationError('PaymentTransaction: invalid Amount')
   }
 
-  if (tx.Destination === undefined) {
-    throw new ValidationError('PaymentTransaction: missing field Destination')
-  }
-
-  if (!isAmount(tx.Destination)) {
-    throw new ValidationError('PaymentTransaction: invalid Destination')
-  }
-
-  if (tx.DestinationTag != null && typeof tx.DestinationTag !== 'number') {
-    throw new ValidationError(
-      'PaymentTransaction: DestinationTag must be a number',
-    )
-  }
+  validateRequiredField(tx, 'Destination', isAccount)
+  validateOptionalField(tx, 'DestinationTag', isNumber)
 
   if (tx.InvoiceID !== undefined && typeof tx.InvoiceID !== 'string') {
     throw new ValidationError('PaymentTransaction: InvoiceID must be a string')

package/src/models/transactions/paymentChannelCreate.ts

@@ -1,6 +1,14 @@
 import { ValidationError } from '../../errors'
 
-import { BaseTransaction, validateBaseTransaction } from './common'
+import {
+  Account,
+  BaseTransaction,
+  isAccount,
+  isNumber,
+  validateBaseTransaction,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
 
 /**
  * Create a unidirectional channel and fund it with XRP. The address sending
@@ -21,7 +29,7 @@ export interface PaymentChannelCreate extends BaseTransaction {
    * Address to receive XRP claims against this channel. This is also known as
    * the "destination address" for the channel.
    */
-  Destination: string
+  Destination: Account
   /**
    * Amount of time the source address must wait before closing the channel if
    * it has unclaimed XRP.
@@ -54,7 +62,6 @@ export interface PaymentChannelCreate extends BaseTransaction {
  * @param tx - An PaymentChannelCreate Transaction.
  * @throws When the PaymentChannelCreate is Malformed.
  */
-// eslint-disable-next-line max-lines-per-function -- okay for this function, there's a lot of things to check
 export function validatePaymentChannelCreate(
   tx: Record<string, unknown>,
 ): void {
@@ -68,15 +75,8 @@ export function validatePaymentChannelCreate(
     throw new ValidationError('PaymentChannelCreate: Amount must be a string')
   }
 
-  if (tx.Destination === undefined) {
-    throw new ValidationError('PaymentChannelCreate: missing Destination')
-  }
-
-  if (typeof tx.Destination !== 'string') {
-    throw new ValidationError(
-      'PaymentChannelCreate: Destination must be a string',
-    )
-  }
+  validateRequiredField(tx, 'Destination', isAccount)
+  validateOptionalField(tx, 'DestinationTag', isNumber)
 
   if (tx.SettleDelay === undefined) {
     throw new ValidationError('PaymentChannelCreate: missing SettleDelay')
@@ -103,13 +103,4 @@ export function validatePaymentChannelCreate(
       'PaymentChannelCreate: CancelAfter must be a number',
     )
   }
-
-  if (
-    tx.DestinationTag !== undefined &&
-    typeof tx.DestinationTag !== 'number'
-  ) {
-    throw new ValidationError(
-      'PaymentChannelCreate: DestinationTag must be a number',
-    )
-  }
 }

package/src/models/transactions/transaction.ts

@@ -18,8 +18,9 @@ import { CheckCancel, validateCheckCancel } from './checkCancel'
 import { CheckCash, validateCheckCash } from './checkCash'
 import { CheckCreate, validateCheckCreate } from './checkCreate'
 import { Clawback, validateClawback } from './clawback'
-import { isIssuedCurrency } from './common'
+import { BaseTransaction, isIssuedCurrency } from './common'
 import { DepositPreauth, validateDepositPreauth } from './depositPreauth'
+import { EnableAmendment } from './enableAmendment'
 import { EscrowCancel, validateEscrowCancel } from './escrowCancel'
 import { EscrowCreate, validateEscrowCreate } from './escrowCreate'
 import { EscrowFinish, validateEscrowFinish } from './escrowFinish'
@@ -53,10 +54,12 @@ import {
   PaymentChannelFund,
   validatePaymentChannelFund,
 } from './paymentChannelFund'
+import { SetFee } from './setFee'
 import { SetRegularKey, validateSetRegularKey } from './setRegularKey'
 import { SignerListSet, validateSignerListSet } from './signerListSet'
 import { TicketCreate, validateTicketCreate } from './ticketCreate'
 import { TrustSet, validateTrustSet } from './trustSet'
+import { UNLModify } from './UNLModify'
 import {
   XChainAccountCreateCommit,
   validateXChainAccountCreateCommit,
@@ -128,12 +131,16 @@ export type Transaction =
   | XChainAccountCreateCommit
   | XChainModifyBridge
 
+export type PseudoTransaction = EnableAmendment | SetFee | UNLModify
+
 /**
  * @category Transaction Models
  */
-export interface TransactionAndMetadata {
-  transaction: Transaction
-  metadata: TransactionMetadata
+export interface TransactionAndMetadata<
+  T extends BaseTransaction = Transaction,
+> {
+  transaction: T
+  metadata: TransactionMetadata<T>
 }
 
 /**

package/src/models/utils/flags.ts

@@ -10,6 +10,8 @@ import { AccountSetTfFlags } from '../transactions/accountSet'
 import { AMMDepositFlags } from '../transactions/AMMDeposit'
 import { AMMWithdrawFlags } from '../transactions/AMMWithdraw'
 import { GlobalFlags } from '../transactions/common'
+import { NFTokenCreateOfferFlags } from '../transactions/NFTokenCreateOffer'
+import { NFTokenMintFlags } from '../transactions/NFTokenMint'
 import { OfferCreateFlags } from '../transactions/offerCreate'
 import { PaymentFlags } from '../transactions/payment'
 import { PaymentChannelClaimFlags } from '../transactions/paymentChannelClaim'
@@ -43,6 +45,19 @@ export function parseAccountRootFlags(
   return flagsInterface
 }
 
+const txToFlag = {
+  AccountSet: AccountSetTfFlags,
+  AMMDeposit: AMMDepositFlags,
+  AMMWithdraw: AMMWithdrawFlags,
+  NFTokenCreateOffer: NFTokenCreateOfferFlags,
+  NFTokenMint: NFTokenMintFlags,
+  OfferCreate: OfferCreateFlags,
+  PaymentChannelClaim: PaymentChannelClaimFlags,
+  Payment: PaymentFlags,
+  TrustSet: TrustSetFlags,
+  XChainModifyBridge: XChainModifyBridgeFlags,
+}
+
 /**
  * Sets a transaction's flags to its numeric representation.
  *
@@ -57,34 +72,9 @@ export function setTransactionFlagsToNumber(tx: Transaction): void {
     return
   }
 
-  switch (tx.TransactionType) {
-    case 'AccountSet':
-      tx.Flags = convertFlagsToNumber(tx.Flags, AccountSetTfFlags)
-      return
-    case 'AMMDeposit':
-      tx.Flags = convertFlagsToNumber(tx.Flags, AMMDepositFlags)
-      return
-    case 'AMMWithdraw':
-      tx.Flags = convertFlagsToNumber(tx.Flags, AMMWithdrawFlags)
-      return
-    case 'OfferCreate':
-      tx.Flags = convertFlagsToNumber(tx.Flags, OfferCreateFlags)
-      return
-    case 'PaymentChannelClaim':
-      tx.Flags = convertFlagsToNumber(tx.Flags, PaymentChannelClaimFlags)
-      return
-    case 'Payment':
-      tx.Flags = convertFlagsToNumber(tx.Flags, PaymentFlags)
-      return
-    case 'TrustSet':
-      tx.Flags = convertFlagsToNumber(tx.Flags, TrustSetFlags)
-      return
-    case 'XChainModifyBridge':
-      tx.Flags = convertFlagsToNumber(tx.Flags, XChainModifyBridgeFlags)
-      return
-    default:
-      tx.Flags = 0
-  }
+  tx.Flags = txToFlag[tx.TransactionType]
+    ? convertFlagsToNumber(tx.Flags, txToFlag[tx.TransactionType])
+    : 0
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- added ValidationError check for flagEnum

package/src/sugar/autofill.ts

@@ -5,7 +5,6 @@ import type { Client } from '..'
 import { ValidationError, XrplError } from '../errors'
 import { AccountInfoRequest, AccountObjectsRequest } from '../models/methods'
 import { Transaction } from '../models/transactions'
-import { setTransactionFlagsToNumber } from '../models/utils/flags'
 import { xrpToDrops } from '../utils'
 
 import getFeeXrp from './getFeeXrp'
@@ -19,83 +18,6 @@ const LEDGER_OFFSET = 20
 const RESTRICTED_NETWORKS = 1024
 const REQUIRED_NETWORKID_VERSION = '1.11.0'
 const HOOKS_TESTNET_ID = 21338
-interface ClassicAccountAndTag {
-  classicAccount: string
-  tag: number | false | undefined
-}
-
-/**
- * Autofills fields in a transaction. This will set `Sequence`, `Fee`,
- * `lastLedgerSequence` according to the current state of the server this Client
- * is connected to. It also converts all X-Addresses to classic addresses and
- * flags interfaces into numbers.
- *
- * @example
- *
- * ```ts
- * const { Client } = require('xrpl')
- *
- * const client = new Client('wss://s.altnet.rippletest.net:51233')
- *
- * async function createAndAutofillTransaction() {
- *   const transaction = {
- *     TransactionType: 'Payment',
- *     Account: 'rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh',
- *     Destination: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
- *     Amount: '10000000' // 10 XRP in drops (1/1,000,000th of an XRP)
- *   }
- *
- *   try {
- *     const autofilledTransaction = await client.autofill(transaction)
- *     console.log(autofilledTransaction)
- *   } catch (error) {
- *     console.error(`Failed to autofill transaction: ${error}`)
- *   }
- * }
- *
- * createAndAutofillTransaction()
- * ```
- *
- * Autofill helps fill in fields which should be included in a transaction, but can be determined automatically
- * such as `LastLedgerSequence` and `Fee`. If you override one of the fields `autofill` changes, your explicit
- * values will be used instead. By default, this is done as part of `submit` and `submitAndWait` when you pass
- * in an unsigned transaction along with your wallet to be submitted.
- *
- * @param this - A client.
- * @param transaction - A {@link Transaction} in JSON format
- * @param signersCount - The expected number of signers for this transaction.
- * Only used for multisigned transactions.
- * @returns The autofilled transaction.
- */
-async function autofill<T extends Transaction>(
-  this: Client,
-  transaction: T,
-  signersCount?: number,
-): Promise<T> {
-  const tx = { ...transaction }
-
-  setValidAddresses(tx)
-
-  setTransactionFlagsToNumber(tx)
-  const promises: Array<Promise<void>> = []
-  if (tx.NetworkID == null) {
-    tx.NetworkID = txNeedsNetworkID(this) ? this.networkID : undefined
-  }
-  if (tx.Sequence == null) {
-    promises.push(setNextValidSequenceNumber(this, tx))
-  }
-  if (tx.Fee == null) {
-    promises.push(calculateFeePerTransactionType(this, tx, signersCount))
-  }
-  if (tx.LastLedgerSequence == null) {
-    promises.push(setLatestValidatedLedgerSequence(this, tx))
-  }
-  if (tx.TransactionType === 'AccountDelete') {
-    promises.push(checkAccountDeleteBlockers(this, tx))
-  }
-
-  return Promise.all(promises).then(() => tx)
-}
 
 /**
  * Determines whether the source rippled version is not later than the target rippled version.
@@ -171,7 +93,7 @@ function isNotLaterRippledVersion(source: string, target: string): boolean {
  * @param client -- The connected client.
  * @returns True if required networkID, false otherwise.
  */
-function txNeedsNetworkID(client: Client): boolean {
+export function txNeedsNetworkID(client: Client): boolean {
   if (
     client.networkID !== undefined &&
     client.networkID > RESTRICTED_NETWORKS
@@ -190,7 +112,17 @@ function txNeedsNetworkID(client: Client): boolean {
   return false
 }
 
-function setValidAddresses(tx: Transaction): void {
+interface ClassicAccountAndTag {
+  classicAccount: string
+  tag: number | false | undefined
+}
+
+/**
+ * Sets valid addresses for the transaction.
+ *
+ * @param tx - The transaction object.
+ */
+export function setValidAddresses(tx: Transaction): void {
   validateAccountAddress(tx, 'Account', 'SourceTag')
   // eslint-disable-next-line @typescript-eslint/dot-notation -- Destination can exist on Transaction
   if (tx['Destination'] != null) {
@@ -206,6 +138,14 @@ function setValidAddresses(tx: Transaction): void {
   convertToClassicAddress(tx, 'RegularKey')
 }
 
+/**
+ * Validates the account address in a transaction object.
+ *
+ * @param tx - The transaction object.
+ * @param accountField - The field name for the account address in the transaction object.
+ * @param tagField - The field name for the tag in the transaction object.
+ * @throws {ValidationError} If the tag field does not match the tag of the account address.
+ */
 function validateAccountAddress(
   tx: Transaction,
   accountField: string,
@@ -227,6 +167,14 @@ function validateAccountAddress(
   }
 }
 
+/**
+ * Retrieves the classic account and tag from an account address.
+ *
+ * @param Account - The account address.
+ * @param [expectedTag] - The expected tag for the account address.
+ * @returns The classic account and tag.
+ * @throws {ValidationError} If the address includes a tag that does not match the tag specified in the transaction.
+ */
 function getClassicAccountAndTag(
   Account: string,
   expectedTag?: number,
@@ -249,6 +197,12 @@ function getClassicAccountAndTag(
   }
 }
 
+/**
+ * Converts the specified field of a transaction object to a classic address format.
+ *
+ * @param tx - The transaction object.
+ * @param fieldName - The name of the field to convert.export
+ */
 function convertToClassicAddress(tx: Transaction, fieldName: string): void {
   // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- assignment is safe
   const account = tx[fieldName]
@@ -259,7 +213,15 @@ function convertToClassicAddress(tx: Transaction, fieldName: string): void {
   }
 }
 
-async function setNextValidSequenceNumber(
+/**
+ * Sets the next valid sequence number for a transaction.
+ *
+ * @param client - The client object used for making requests.
+ * @param tx - The transaction object for which the sequence number needs to be set.
+ * @returns A Promise that resolves when the sequence number is set.
+ * @throws {Error} If there is an error retrieving the account information.
+ */
+export async function setNextValidSequenceNumber(
   client: Client,
   tx: Transaction,
 ): Promise<void> {
@@ -273,7 +235,14 @@ async function setNextValidSequenceNumber(
   tx.Sequence = data.result.account_data.Sequence
 }
 
-async function fetchOwnerReserveFee(client: Client): Promise<BigNumber> {
+/**
+ * Fetches the account deletion fee from the server state using the provided client.
+ *
+ * @param client - The client object used to make the request.
+ * @returns A Promise that resolves to the account deletion fee as a BigNumber.
+ * @throws {Error} Throws an error if the account deletion fee cannot be fetched.
+ */
+async function fetchAccountDeleteFee(client: Client): Promise<BigNumber> {
   const response = await client.request({ command: 'server_state' })
   const fee = response.result.state.validated_ledger?.reserve_inc
 
@@ -284,7 +253,15 @@ async function fetchOwnerReserveFee(client: Client): Promise<BigNumber> {
   return new BigNumber(fee)
 }
 
-async function calculateFeePerTransactionType(
+/**
+ * Calculates the fee per transaction type.
+ *
+ * @param client - The client object.
+ * @param tx - The transaction object.
+ * @param [signersCount=0] - The number of signers (default is 0). Only used for multisigning.
+ * @returns A promise that resolves with void. Modifies the `tx` parameter to give it the calculated fee.
+ */
+export async function calculateFeePerTransactionType(
   client: Client,
   tx: Transaction,
   signersCount = 0,
@@ -309,7 +286,7 @@ async function calculateFeePerTransactionType(
     tx.TransactionType === 'AccountDelete' ||
     tx.TransactionType === 'AMMCreate'
   ) {
-    baseFee = await fetchOwnerReserveFee(client)
+    baseFee = await fetchAccountDeleteFee(client)
   }
 
   /*
@@ -331,11 +308,25 @@ async function calculateFeePerTransactionType(
   tx.Fee = totalFee.dp(0, BigNumber.ROUND_CEIL).toString(10)
 }
 
+/**
+ * Scales the given value by multiplying it with the provided multiplier.
+ *
+ * @param value - The value to be scaled.
+ * @param multiplier - The multiplier to scale the value.
+ * @returns The scaled value as a string.
+ */
 function scaleValue(value, multiplier): string {
   return new BigNumber(value).times(multiplier).toString()
 }
 
-async function setLatestValidatedLedgerSequence(
+/**
+ * Sets the latest validated ledger sequence for the transaction.
+ *
+ * @param client - The client object.
+ * @param tx - The transaction object.
+ * @returns A promise that resolves with void. Modifies the `tx` parameter setting `LastLedgerSequence`.
+ */
+export async function setLatestValidatedLedgerSequence(
   client: Client,
   tx: Transaction,
 ): Promise<void> {
@@ -344,7 +335,14 @@ async function setLatestValidatedLedgerSequence(
   tx.LastLedgerSequence = ledgerSequence + LEDGER_OFFSET
 }
 
-async function checkAccountDeleteBlockers(
+/**
+ * Checks for any blockers that prevent the deletion of an account.
+ *
+ * @param client - The client object.
+ * @param tx - The transaction object.
+ * @returns A promise that resolves with void if there are no blockers, or rejects with an XrplError if there are blockers.
+ */
+export async function checkAccountDeleteBlockers(
   client: Client,
   tx: Transaction,
 ): Promise<void> {
@@ -367,5 +365,3 @@ async function checkAccountDeleteBlockers(
     resolve()
   })
 }
-
-export default autofill