xrpl 4.1.0 → 4.2.0-batch.0

package/src/models/methods/index.ts

@@ -148,6 +148,14 @@ import {
   StateAccountingFinal,
 } from './serverInfo'
 import { ServerStateRequest, ServerStateResponse } from './serverState'
+import {
+  SimulateBinaryRequest,
+  SimulateBinaryResponse,
+  SimulateJsonRequest,
+  SimulateJsonResponse,
+  SimulateRequest,
+  SimulateResponse,
+} from './simulate'
 import { SubmitRequest, SubmitResponse } from './submit'
 import {
   SubmitMultisignedRequest,
@@ -203,6 +211,7 @@ type Request =
   | LedgerDataRequest
   | LedgerEntryRequest
   // transaction methods
+  | SimulateRequest
   | SubmitRequest
   | SubmitMultisignedRequest
   | TransactionEntryRequest
@@ -261,6 +270,7 @@ type Response<Version extends APIVersion = typeof DEFAULT_API_VERSION> =
   | LedgerDataResponse
   | LedgerEntryResponse
   // transaction methods
+  | SimulateResponse
   | SubmitResponse
   | SubmitMultisignedVersionResponseMap<Version>
   | TransactionEntryResponse
@@ -398,6 +408,12 @@ export type RequestResponseMap<
   ? LedgerDataResponse
   : T extends LedgerEntryRequest
   ? LedgerEntryResponse
+  : T extends SimulateBinaryRequest
+  ? SimulateBinaryResponse
+  : T extends SimulateJsonRequest
+  ? SimulateJsonResponse
+  : T extends SimulateRequest
+  ? SimulateJsonResponse
   : T extends SubmitRequest
   ? SubmitResponse
   : T extends SubmitMultisignedRequest
@@ -544,6 +560,8 @@ export {
   LedgerEntryRequest,
   LedgerEntryResponse,
   // transaction methods with types
+  SimulateRequest,
+  SimulateResponse,
   SubmitRequest,
   SubmitResponse,
   SubmitMultisignedRequest,

package/src/models/methods/ledger.ts

@@ -203,13 +203,13 @@ export interface LedgerQueueData {
 }
 
 export interface LedgerBinary
-  extends Omit<Omit<Ledger, 'transactions'>, 'accountState'> {
+  extends Omit<Ledger, 'transactions' | 'accountState'> {
   accountState?: string[]
   transactions?: string[]
 }
 
 export interface LedgerBinaryV1
-  extends Omit<Omit<LedgerV1, 'transactions'>, 'accountState'> {
+  extends Omit<LedgerV1, 'transactions' | 'accountState'> {
   accountState?: string[]
   transactions?: string[]
 }

package/src/models/methods/serverState.ts

@@ -51,6 +51,7 @@ export interface ServerStateResponse extends BaseResponse {
       load_factor_fee_queue?: number
       load_factor_fee_reference?: number
       load_factor_server?: number
+      network_id: number
       peer_disconnects?: string
       peer_disconnects_resources?: string
       peers: number

package/src/models/methods/simulate.ts

@@ -0,0 +1,88 @@
+import {
+  BaseTransaction,
+  Transaction,
+  TransactionMetadata,
+} from '../transactions'
+
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The `simulate` method simulates a transaction without submitting it to the network.
+ * Returns a {@link SimulateResponse}.
+ *
+ * @category Requests
+ */
+export type SimulateRequest = BaseRequest & {
+  command: 'simulate'
+
+  binary?: boolean
+} & (
+    | {
+        tx_blob: string
+        tx_json?: never
+      }
+    | {
+        tx_json: Transaction
+        tx_blob?: never
+      }
+  )
+
+export type SimulateBinaryRequest = SimulateRequest & {
+  binary: true
+}
+
+export type SimulateJsonRequest = SimulateRequest & {
+  binary?: false
+}
+
+/**
+ * Response expected from an {@link SimulateRequest}.
+ *
+ * @category Responses
+ */
+export type SimulateResponse = SimulateJsonResponse | SimulateBinaryResponse
+
+export interface SimulateBinaryResponse extends BaseResponse {
+  result: {
+    applied: false
+
+    engine_result: string
+
+    engine_result_code: number
+
+    engine_result_message: string
+
+    tx_blob: string
+
+    meta_blob: string
+
+    /**
+     * The ledger index of the ledger version that was used to generate this
+     * response.
+     */
+    ledger_index: number
+  }
+}
+
+export interface SimulateJsonResponse<T extends BaseTransaction = Transaction>
+  extends BaseResponse {
+  result: {
+    applied: false
+
+    engine_result: string
+
+    engine_result_code: number
+
+    engine_result_message: string
+
+    /**
+     * The ledger index of the ledger version that was used to generate this
+     * response.
+     */
+    ledger_index: number
+
+    tx_json: T
+
+    meta?: TransactionMetadata<T>
+  }
+}

package/src/models/transactions/AMMClawback.ts

@@ -0,0 +1,120 @@
+import { ValidationError } from '../../errors'
+import { Currency, IssuedCurrency, IssuedCurrencyAmount } from '../common'
+
+import {
+  Account,
+  BaseTransaction,
+  GlobalFlagsInterface,
+  isAccount,
+  isAmount,
+  isCurrency,
+  validateBaseTransaction,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
+
+/**
+ * Enum representing values for AMMClawback Transaction Flags.
+ *
+ * @category Transaction Flags
+ */
+export enum AMMClawbackFlags {
+  tfClawTwoAssets = 0x00000001,
+}
+
+/**
+ * Map of flags to boolean values representing {@link AMMClawback} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface AMMClawbackFlagsInterface extends GlobalFlagsInterface {
+  tfClawTwoAssets?: boolean
+}
+
+/**
+ * Claw back tokens from a holder that has deposited your issued tokens into an AMM pool.
+ *
+ * Clawback is disabled by default. To use clawback, you must send an AccountSet transaction to enable the
+ * Allow Trust Line Clawback setting. An issuer with any existing tokens cannot enable clawback. You can
+ * only enable Allow Trust Line Clawback if you have a completely empty owner directory, meaning you must
+ * do so before you set up any trust lines, offers, escrows, payment channels, checks, or signer lists.
+ * After you enable clawback, it cannot reverted: the account permanently gains the ability to claw back
+ * issued assets on trust lines.
+ */
+export interface AMMClawback extends BaseTransaction {
+  TransactionType: 'AMMClawback'
+
+  /**
+   * The account holding the asset to be clawed back.
+   */
+  Holder: Account
+
+  /**
+   * Specifies the asset that the issuer wants to claw back from the AMM pool.
+   * In JSON, this is an object with currency and issuer fields. The issuer field must match with Account.
+   */
+  Asset: IssuedCurrency
+
+  /**
+   * Specifies the other asset in the AMM's pool. In JSON, this is an object with currency and
+   * issuer fields (omit issuer for XRP).
+   */
+  Asset2: Currency
+
+  /**
+   * The maximum amount to claw back from the AMM account. The currency and issuer subfields should match
+   * the Asset subfields. If this field isn't specified, or the value subfield exceeds the holder's available
+   * tokens in the AMM, all of the holder's tokens will be clawed back.
+   */
+  Amount?: IssuedCurrencyAmount
+}
+
+/**
+ * Verify the form and type of an AMMClawback at runtime.
+ *
+ * @param tx - An AMMClawback Transaction.
+ * @throws {ValidationError} When the transaction is malformed.
+ */
+export function validateAMMClawback(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'Holder', isAccount)
+
+  validateRequiredField(tx, 'Asset', isCurrency)
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- required
+  const asset = tx.Asset as IssuedCurrency
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- required
+  const amount = tx.Amount as IssuedCurrencyAmount
+
+  if (tx.Holder === asset.issuer) {
+    throw new ValidationError(
+      'AMMClawback: Holder and Asset.issuer must be distinct',
+    )
+  }
+
+  if (tx.Account !== asset.issuer) {
+    throw new ValidationError(
+      'AMMClawback: Account must be the same as Asset.issuer',
+    )
+  }
+
+  validateRequiredField(tx, 'Asset2', isCurrency)
+
+  validateOptionalField(tx, 'Amount', isAmount)
+
+  if (tx.Amount != null) {
+    if (amount.currency !== asset.currency) {
+      throw new ValidationError(
+        'AMMClawback: Amount.currency must match Asset.currency',
+      )
+    }
+
+    if (amount.issuer !== asset.issuer) {
+      throw new ValidationError(
+        'AMMClawback: Amount.issuer must match Amount.issuer',
+      )
+    }
+  }
+}

package/src/models/transactions/AMMDeposit.ts

@@ -3,7 +3,7 @@ import { Amount, Currency, IssuedCurrencyAmount } from '../common'
 
 import {
   BaseTransaction,
-  GlobalFlags,
+  GlobalFlagsInterface,
   isAmount,
   isCurrency,
   isIssuedCurrency,
@@ -24,7 +24,7 @@ export enum AMMDepositFlags {
   tfTwoAssetIfEmpty = 0x00800000,
 }
 
-export interface AMMDepositFlagsInterface extends GlobalFlags {
+export interface AMMDepositFlagsInterface extends GlobalFlagsInterface {
   tfLPToken?: boolean
   tfSingleAsset?: boolean
   tfTwoAsset?: boolean

package/src/models/transactions/AMMWithdraw.ts

@@ -3,7 +3,7 @@ import { Amount, Currency, IssuedCurrencyAmount } from '../common'
 
 import {
   BaseTransaction,
-  GlobalFlags,
+  GlobalFlagsInterface,
   isAmount,
   isCurrency,
   isIssuedCurrency,
@@ -25,7 +25,7 @@ export enum AMMWithdrawFlags {
   tfLimitLPToken = 0x00400000,
 }
 
-export interface AMMWithdrawFlagsInterface extends GlobalFlags {
+export interface AMMWithdrawFlagsInterface extends GlobalFlagsInterface {
   tfLPToken?: boolean
   tfWithdrawAll?: boolean
   tfOneAssetWithdrawAll?: boolean

package/src/models/transactions/MPTokenAuthorize.ts

@@ -6,7 +6,7 @@ import {
   Account,
   validateOptionalField,
   isAccount,
-  GlobalFlags,
+  GlobalFlagsInterface,
 } from './common'
 
 /**
@@ -32,7 +32,7 @@ export enum MPTokenAuthorizeFlags {
  *
  * @category Transaction Flags
  */
-export interface MPTokenAuthorizeFlagsInterface extends GlobalFlags {
+export interface MPTokenAuthorizeFlagsInterface extends GlobalFlagsInterface {
   tfMPTUnauthorize?: boolean
 }
 

package/src/models/transactions/MPTokenIssuanceCreate.ts

@@ -3,7 +3,7 @@ import { isHex, INTEGER_SANITY_CHECK, isFlagEnabled } from '../utils'
 
 import {
   BaseTransaction,
-  GlobalFlags,
+  GlobalFlagsInterface,
   validateBaseTransaction,
   validateOptionalField,
   isString,
@@ -58,7 +58,8 @@ export enum MPTokenIssuanceCreateFlags {
  *
  * @category Transaction Flags
  */
-export interface MPTokenIssuanceCreateFlagsInterface extends GlobalFlags {
+export interface MPTokenIssuanceCreateFlagsInterface
+  extends GlobalFlagsInterface {
   tfMPTCanLock?: boolean
   tfMPTRequireAuth?: boolean
   tfMPTCanEscrow?: boolean

package/src/models/transactions/MPTokenIssuanceSet.ts

@@ -9,7 +9,7 @@ import {
   Account,
   validateOptionalField,
   isAccount,
-  GlobalFlags,
+  GlobalFlagsInterface,
 } from './common'
 
 /**
@@ -34,7 +34,7 @@ export enum MPTokenIssuanceSetFlags {
  *
  * @category Transaction Flags
  */
-export interface MPTokenIssuanceSetFlagsInterface extends GlobalFlags {
+export interface MPTokenIssuanceSetFlagsInterface extends GlobalFlagsInterface {
   tfMPTLock?: boolean
   tfMPTUnlock?: boolean
 }

package/src/models/transactions/NFTokenCreateOffer.ts

@@ -4,7 +4,7 @@ import { isFlagEnabled } from '../utils'
 
 import {
   BaseTransaction,
-  GlobalFlags,
+  GlobalFlagsInterface,
   validateBaseTransaction,
   isAmount,
   parseAmountValue,
@@ -33,7 +33,7 @@ export enum NFTokenCreateOfferFlags {
  *
  * @category Transaction Flags
  */
-export interface NFTokenCreateOfferFlagsInterface extends GlobalFlags {
+export interface NFTokenCreateOfferFlagsInterface extends GlobalFlagsInterface {
   tfSellNFToken?: boolean
 }
 

package/src/models/transactions/NFTokenMint.ts

@@ -4,7 +4,7 @@ import { isHex } from '../utils'
 import {
   Account,
   BaseTransaction,
-  GlobalFlags,
+  GlobalFlagsInterface,
   isAccount,
   validateBaseTransaction,
   validateOptionalField,
@@ -38,6 +38,10 @@ export enum NFTokenMintFlags {
    * issuer.
    */
   tfTransferable = 0x00000008,
+  /**
+   * If set, indicates that this NFT's URI can be modified.
+   */
+  tfMutable = 0x00000010,
 }
 
 /**
@@ -46,11 +50,12 @@ export enum NFTokenMintFlags {
  *
  * @category Transaction Flags
  */
-export interface NFTokenMintFlagsInterface extends GlobalFlags {
+export interface NFTokenMintFlagsInterface extends GlobalFlagsInterface {
   tfBurnable?: boolean
   tfOnlyXRP?: boolean
   tfTrustLine?: boolean
   tfTransferable?: boolean
+  tfMutable?: boolean
 }
 
 /**

package/src/models/transactions/NFTokenModify.ts

@@ -0,0 +1,67 @@
+import { ValidationError } from '../../errors'
+import { isHex } from '../utils'
+
+import {
+  BaseTransaction,
+  validateBaseTransaction,
+  isAccount,
+  isString,
+  validateOptionalField,
+  Account,
+  validateRequiredField,
+} from './common'
+
+/**
+ * The NFTokenModify transaction modifies an NFToken's URI
+ * if its tfMutable is set to true.
+ */
+export interface NFTokenModify extends BaseTransaction {
+  TransactionType: 'NFTokenModify'
+  /**
+   * Identifies the NFTokenID of the NFToken object that the
+   * offer references.
+   */
+  NFTokenID: string
+  /**
+   * Indicates the AccountID of the account that owns the corresponding NFToken.
+   * Can be omitted if the owner is the account submitting this transaction
+   */
+  Owner?: Account
+  /**
+   * URI that points to the data and/or metadata associated with the NFT.
+   * This field need not be an HTTP or HTTPS URL; it could be an IPFS URI, a
+   * magnet link, immediate data encoded as an RFC2379 "data" URL, or even an
+   * opaque issuer-specific encoding. The URI is NOT checked for validity, but
+   * the field is limited to a maximum length of 256 bytes.
+   *
+   * This field must be hex-encoded. You can use `convertStringToHex` to
+   * convert this field to the proper encoding.
+   *
+   * This field must not be an empty string. Omit it from the transaction or
+   * set to `null` if you do not use it.
+   */
+  URI?: string | null
+}
+
+/**
+ * Verify the form and type of an NFTokenModify at runtime.
+ *
+ * @param tx - An NFTokenModify Transaction.
+ * @throws When the NFTokenModify is Malformed.
+ */
+export function validateNFTokenModify(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'NFTokenID', isString)
+  validateOptionalField(tx, 'Owner', isAccount)
+  validateOptionalField(tx, 'URI', isString)
+
+  if (tx.URI !== undefined && typeof tx.URI === 'string') {
+    if (tx.URI === '') {
+      throw new ValidationError('NFTokenModify: URI must not be empty string')
+    }
+    if (!isHex(tx.URI)) {
+      throw new ValidationError('NFTokenModify: URI must be in hex format')
+    }
+  }
+}

package/src/models/transactions/XChainModifyBridge.ts

@@ -2,7 +2,7 @@ import { Amount, XChainBridge } from '../common'
 
 import {
   BaseTransaction,
-  GlobalFlags,
+  GlobalFlagsInterface,
   isAmount,
   isXChainBridge,
   validateBaseTransaction,
@@ -26,7 +26,7 @@ export enum XChainModifyBridgeFlags {
  *
  * @category Transaction Flags
  */
-export interface XChainModifyBridgeFlagsInterface extends GlobalFlags {
+export interface XChainModifyBridgeFlagsInterface extends GlobalFlagsInterface {
   /** Clears the MinAccountCreateAmount of the bridge. */
   tfClearAccountCreateAmount?: boolean
 }

package/src/models/transactions/accountDelete.ts

@@ -7,6 +7,7 @@ import {
   validateCredentialsList,
   validateOptionalField,
   validateRequiredField,
+  MAX_AUTHORIZED_CREDENTIALS,
 } from './common'
 
 /**
@@ -54,5 +55,6 @@ export function validateAccountDelete(tx: Record<string, unknown>): void {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- known from base check
     tx.TransactionType as string,
     true,
+    MAX_AUTHORIZED_CREDENTIALS,
   )
 }

package/src/models/transactions/accountSet.ts

@@ -3,6 +3,7 @@ import { ValidationError } from '../../errors'
 import {
   Account,
   BaseTransaction,
+  GlobalFlagsInterface,
   isAccount,
   validateBaseTransaction,
   validateOptionalField,
@@ -112,7 +113,7 @@ export enum AccountSetTfFlags {
  * // }
  * ```
  */
-export interface AccountSetFlagsInterface {
+export interface AccountSetFlagsInterface extends GlobalFlagsInterface {
   tfRequireDestTag?: boolean
   tfOptionalDestTag?: boolean
   tfRequireAuth?: boolean

package/src/models/transactions/batch.ts

@@ -0,0 +1,147 @@
+import { ValidationError } from '../../errors'
+import { Signer } from '../common'
+
+import {
+  BaseTransaction,
+  GlobalFlagsInterface,
+  isArray,
+  isObject,
+  isString,
+  validateBaseTransaction,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
+import type { SubmittableTransaction } from './transaction'
+
+/**
+ * Enum representing values of {@link Batch} transaction flags.
+ *
+ * @category Transaction Flags
+ */
+export enum BatchFlags {
+  tfAllOrNothing = 0x00010000,
+  tfOnlyOne = 0x00020000,
+  tfUntilFailure = 0x00040000,
+  tfIndependent = 0x00080000,
+}
+
+/**
+ * Map of flags to boolean values representing {@link Batch} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface BatchFlagsInterface extends GlobalFlagsInterface {
+  tfAllOrNothing?: boolean
+  tfOnlyOne?: boolean
+  tfUntilFailure?: boolean
+  tfIndependent?: boolean
+}
+
+export type BatchInnerTransaction = SubmittableTransaction & {
+  Fee?: '0'
+
+  SigningPubKey?: ''
+
+  TxnSignature?: never
+
+  Signers?: never
+
+  LastLedgerSequence?: never
+}
+
+export interface BatchSigner {
+  BatchSigner: {
+    Account: string
+
+    SigningPubKey?: string
+
+    TxnSignature?: string
+
+    Signers?: Signer[]
+  }
+}
+
+/**
+ * @category Transaction Models
+ */
+export interface Batch extends BaseTransaction {
+  TransactionType: 'Batch'
+
+  BatchSigners?: BatchSigner[]
+
+  RawTransactions: Array<{
+    RawTransaction: BatchInnerTransaction
+  }>
+}
+
+/**
+ * Verify the form and type of a Batch at runtime.
+ *
+ * @param tx - A Batch Transaction.
+ * @throws When the Batch is malformed.
+ */
+// eslint-disable-next-line max-lines-per-function -- needed here due to the complexity
+export function validateBatch(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'RawTransactions', isArray)
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+  const rawTransactions = tx.RawTransactions as unknown[]
+  rawTransactions.forEach((rawTxObj, index) => {
+    if (!isObject(rawTxObj)) {
+      throw new ValidationError(
+        `Batch: RawTransactions[${index}] is not object.`,
+      )
+    }
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+    const rawTxRecord = rawTxObj as Record<string, unknown>
+    validateRequiredField(rawTxRecord, 'RawTransaction', isObject, {
+      paramName: `RawTransactions[${index}].RawTransaction`,
+      txType: 'Batch',
+    })
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+    const rawTx = rawTxRecord.RawTransaction as Record<string, unknown>
+    if (rawTx.TransactionType === 'Batch') {
+      throw new ValidationError(
+        `Batch: RawTransactions[${index}] is a Batch transaction. Cannot nest Batch transactions.`,
+      )
+    }
+  })
+  // Full validation of each `RawTransaction` object is done in `validate` to avoid dependency cycles
+
+  validateOptionalField(tx, 'BatchSigners', isArray)
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+  const batchSigners = tx.BatchSigners as unknown[] | undefined
+  batchSigners?.forEach((signerObj, index) => {
+    if (!isObject(signerObj)) {
+      throw new ValidationError(`Batch: BatchSigners[${index}] is not object.`)
+    }
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+    const signerRecord = signerObj as Record<string, unknown>
+    validateRequiredField(signerRecord, 'BatchSigner', isObject, {
+      paramName: `BatchSigners[${index}].BatchSigner`,
+      txType: 'Batch',
+    })
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- checked above
+    const signer = signerRecord.BatchSigner as Record<string, unknown>
+    validateRequiredField(signer, 'Account', isString, {
+      paramName: `BatchSigners[${index}].Account`,
+      txType: 'Batch',
+    })
+    validateOptionalField(signer, 'SigningPubKey', isString, {
+      paramName: `BatchSigners[${index}].SigningPubKey`,
+      txType: 'Batch',
+    })
+    validateOptionalField(signer, 'TxnSignature', isString, {
+      paramName: `BatchSigners[${index}].TxnSignature`,
+      txType: 'Batch',
+    })
+    validateOptionalField(signer, 'Signers', isArray, {
+      paramName: `BatchSigners[${index}].Signers`,
+      txType: 'Batch',
+    })
+  })
+}