xrpl 2.14.1 → 2.14.2

package/src/models/methods/ledgerEntry.ts

@@ -21,6 +21,22 @@ import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
  */
 export interface LedgerEntryRequest extends BaseRequest, LookupByLedgerRequest {
   command: 'ledger_entry'
+
+  /**
+   * Retrieve a MPTokenIssuance object from the ledger.
+   */
+  mpt_issuance?: string
+
+  /**
+   * Retrieve a MPToken object from the ledger.
+   */
+  mptoken?:
+    | {
+        mpt_issuance_id: string
+        account: string
+      }
+    | string
+
   /**
    * Retrieve an Automated Market Maker (AMM) object from the ledger.
    * This is similar to amm_info method, but the ledger_entry version returns only the ledger entry as stored.
@@ -35,7 +51,14 @@ export interface LedgerEntryRequest extends BaseRequest, LookupByLedgerRequest {
       issuer?: string
     }
   }
-
+  /**
+   * (Optional) If set to true and the queried object has been deleted,
+   * return its complete data prior to its deletion.
+   * If set to false or not provided and the queried object has been deleted,
+   * return objectNotFound (current behavior).
+   * This parameter is supported only by Clio servers
+   */
+  include_deleted?: boolean
   /**
    * If true, return the requested ledger object's contents as a hex string in
    * the XRP Ledger's binary format. Otherwise, return data in JSON format. The
@@ -60,6 +83,23 @@ export interface LedgerEntryRequest extends BaseRequest, LookupByLedgerRequest {
   /** The object ID of a Check object to retrieve. */
   check?: string
 
+  /* Specify the Credential to retrieve. If a string, must be the ledger entry ID of
+   * the entry, as hexadecimal. If an object, requires subject, issuer, and
+   * credential_type sub-fields.
+   */
+  credential?:
+    | {
+        /** The account that is the subject of the credential. */
+        subject: string
+
+        /** The account that issued the credential. */
+        issuer: string
+
+        /** The type of the credential, as issued. */
+        credentialType: string
+      }
+    | string
+
   /**
    * Specify a DepositPreauth object to retrieve. If a string, must be the
    * object ID of the DepositPreauth object, as hexadecimal. If an object,
@@ -204,5 +244,9 @@ export interface LedgerEntryResponse<T = LedgerEntry> extends BaseResponse {
     /** The binary representation of the ledger object, as hexadecimal. */
     node_binary?: string
     validated?: boolean
+    /**
+     * (Optional) Indicates the ledger index at which the object was deleted.
+     */
+    deleted_ledger_index?: number
   }
 }

package/src/models/methods/nftsByIssuer.ts

@@ -0,0 +1,68 @@
+import { NFToken } from '../common'
+
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+/**
+ * The nfts_by_issuer method returns a list of NFTokens issued by the account.
+ * The order of the NFTs is not associated with the date the NFTs were minted.
+ * Expects a response in the form of a {@link
+ * NFTsByIssuerResponse}.
+ *
+ * @category Requests
+ */
+export interface NFTsByIssuerRequest
+  extends BaseRequest,
+    LookupByLedgerRequest {
+  command: 'nfts_by_issuer'
+  /**
+   * A unique identifier for the account, most commonly the account's address
+   */
+  issuer: string
+  /**
+   * Value from a previous paginated response. Resume retrieving data where
+   * that response left off. This value is stable even if there is a change in
+   * the server's range of available ledgers.
+   */
+  marker?: unknown
+  /**
+   * Filter NFTs issued by this issuer that have this taxon.
+   */
+  nft_taxon?: number
+  /**
+   * Default varies. Limit the number of transactions to retrieve. The server
+   * is not required to honor this value.
+   */
+  limit?: number
+}
+
+/**
+ * Expected response from an {@link NFTsByIssuerRequest}.
+ *
+ * @category Responses
+ */
+export interface NFTsByIssuerResponse extends BaseResponse {
+  result: {
+    /**
+     * The unique identifier for the account, most commonly the account's address
+     */
+    issuer: string
+    /**
+     * A list of NFTs issued by the account.
+     * The order of the NFTs is not associated with the date the NFTs were minted.
+     */
+    nfts: NFToken[]
+    /**
+     * Server-defined value indicating the response is paginated. Pass this
+     * to the next call to resume where this call left off.
+     */
+    marker?: unknown
+    /**
+     * The limit value used in the request.
+     */
+    limit?: number
+    /**
+     * Use to filter NFTs issued by this issuer that have this taxon.
+     */
+    nft_taxon?: number
+  }
+}

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/methods/submit.ts

@@ -1,4 +1,4 @@
-import { Transaction } from '../transactions'
+import { SubmittableTransaction } from '../transactions'
 
 import { BaseRequest, BaseResponse } from './baseMethod'
 
@@ -39,7 +39,7 @@ export interface SubmitResponse extends BaseResponse {
     /** The complete transaction in hex string format. */
     tx_blob: string
     /** The complete transaction in JSON format. */
-    tx_json: Transaction & { hash?: string }
+    tx_json: SubmittableTransaction & { hash?: string }
     /**
      * The value true indicates that the transaction was applied, queued,
      * broadcast, or kept for later. The value `false` indicates that none of

package/src/models/methods/submitMultisigned.ts

@@ -1,3 +1,4 @@
+import { APIVersion, DEFAULT_API_VERSION, RIPPLED_API_V1 } from '../common'
 import { Transaction } from '../transactions'
 
 import { BaseRequest, BaseResponse } from './baseMethod'
@@ -24,28 +25,59 @@ export interface SubmitMultisignedRequest extends BaseRequest {
   fail_hard?: boolean
 }
 
+/**
+ * Common properties for multisigned transaction responses.
+ *
+ * @category Responses
+ */
+interface BaseSubmitMultisignedResult {
+  /**
+   * Code indicating the preliminary result of the transaction, for example.
+   * `tesSUCCESS`.
+   */
+  engine_result: string
+  /**
+   * Numeric code indicating the preliminary result of the transaction,
+   * directly correlated to `engine_result`.
+   */
+  engine_result_code: number
+  /** Human-readable explanation of the preliminary transaction result. */
+  engine_result_message: string
+  /** The complete transaction in hex string format. */
+  tx_blob: string
+  /** The complete transaction in JSON format. */
+  tx_json: Transaction
+}
+
 /**
  * Response expected from a {@link SubmitMultisignedRequest}.
  *
  * @category Responses
  */
 export interface SubmitMultisignedResponse extends BaseResponse {
-  result: {
-    /**
-     * Code indicating the preliminary result of the transaction, for example.
-     * `tesSUCCESS` .
-     */
-    engine_result: string
-    /**
-     * Numeric code indicating the preliminary result of the transaction,
-     * directly correlated to `engine_result`.
-     */
-    engine_result_code: number
-    /** Human-readable explanation of the preliminary transaction result. */
-    engine_result_message: string
-    /** The complete transaction in hex string format. */
-    tx_blob: string
-    /** The complete transaction in JSON format. */
+  result: BaseSubmitMultisignedResult & {
+    hash?: string
+  }
+}
+
+/**
+ * Response expected from a {@link SubmitMultisignedRequest} using api_version 1.
+ *
+ * @category ResponsesV1
+ */
+export interface SubmitMultisignedV1Response extends BaseResponse {
+  result: BaseSubmitMultisignedResult & {
     tx_json: Transaction & { hash?: string }
   }
 }
+
+/**
+ * Type to map between the API version and the response type.
+ *
+ * @category Responses
+ */
+export type SubmitMultisignedVersionResponseMap<
+  Version extends APIVersion = typeof DEFAULT_API_VERSION,
+> = Version extends typeof RIPPLED_API_V1
+  ? SubmitMultisignedV1Response
+  : SubmitMultisignedResponse

package/src/models/methods/subscribe.ts

@@ -4,12 +4,17 @@ import type {
   Path,
   StreamType,
   ResponseOnlyTxInfo,
+  APIVersion,
+  DEFAULT_API_VERSION,
+  RIPPLED_API_V1,
+  RIPPLED_API_V2,
 } from '../common'
 import { Offer } from '../ledger'
 import { OfferCreate, Transaction } from '../transactions'
 import { TransactionMetadata } from '../transactions/metadata'
 
 import type { BaseRequest, BaseResponse } from './baseMethod'
+import { ManifestRequest } from './manifest'
 
 export interface SubscribeBook {
   /**
@@ -261,9 +266,16 @@ export interface ValidationStream extends BaseStream {
  *
  * @category Streams
  */
-export interface TransactionStream extends BaseStream {
+interface TransactionStreamBase<
+  Version extends APIVersion = typeof DEFAULT_API_VERSION,
+> extends BaseStream {
   status: string
   type: 'transaction'
+  /**
+   * The approximate time this ledger was closed, in date time string format.
+   * Always uses the UTC time zone.
+   */
+  close_time_iso: string
   /** String Transaction result code. */
   engine_result: string
   /** Numeric transaction response code, if applicable. */
@@ -284,8 +296,14 @@ export interface TransactionStream extends BaseStream {
    * in detail.
    */
   meta?: TransactionMetadata
-  /** The definition of the transaction in JSON format. */
-  transaction: Transaction & ResponseOnlyTxInfo
+  /** JSON object defining the transaction. */
+  tx_json?: Version extends typeof RIPPLED_API_V2
+    ? Transaction & ResponseOnlyTxInfo
+    : never
+  /** JSON object defining the transaction in rippled API v1. */
+  transaction?: Version extends typeof RIPPLED_API_V1
+    ? Transaction & ResponseOnlyTxInfo
+    : never
   /**
    * If true, this transaction is included in a validated ledger and its
    * outcome is final. Responses from the transaction stream should always be
@@ -295,6 +313,20 @@ export interface TransactionStream extends BaseStream {
   warnings?: Array<{ id: number; message: string }>
 }
 
+/**
+ * Expected response from an {@link AccountTxRequest}.
+ *
+ * @category Streams
+ */
+export type TransactionStream = TransactionStreamBase
+
+/**
+ * Expected response from an {@link AccountTxRequest} with `api_version` set to 1.
+ *
+ * @category Streams
+ */
+export type TransactionV1Stream = TransactionStreamBase<typeof RIPPLED_API_V1>
+
 /**
  * The admin-only `peer_status` stream reports a large amount of information on
  * the activities of other rippled servers to which this server is connected, in
@@ -433,3 +465,38 @@ export type Stream =
   | PeerStatusStream
   | OrderBookStream
   | ConsensusStream
+
+export type EventTypes =
+  | 'connected'
+  | 'disconnected'
+  | 'ledgerClosed'
+  | 'validationReceived'
+  | 'transaction'
+  | 'peerStatusChange'
+  | 'consensusPhase'
+  | 'manifestReceived'
+  | 'path_find'
+  | 'error'
+
+export type OnEventToListenerMap<T extends EventTypes> = T extends 'connected'
+  ? () => void
+  : T extends 'disconnected'
+  ? (code: number) => void
+  : T extends 'ledgerClosed'
+  ? (ledger: LedgerStream) => void
+  : T extends 'validationReceived'
+  ? (validation: ValidationStream) => void
+  : T extends 'transaction'
+  ? (transaction: TransactionStream) => void
+  : T extends 'peerStatusChange'
+  ? (peerStatus: PeerStatusStream) => void
+  : T extends 'consensusPhase'
+  ? (consensus: ConsensusStream) => void
+  : T extends 'manifestReceived'
+  ? (manifest: ManifestRequest) => void
+  : T extends 'path_find'
+  ? (path: PathFindStream) => void
+  : T extends 'error'
+  ? // eslint-disable-next-line @typescript-eslint/no-explicit-any -- needs to be any for overload
+    (...err: any[]) => void
+  : (...args: never[]) => void

package/src/models/methods/tx.ts

@@ -1,6 +1,11 @@
+import {
+  APIVersion,
+  DEFAULT_API_VERSION,
+  RIPPLED_API_V1,
+  RIPPLED_API_V2,
+} from '../common'
 import { Transaction, TransactionMetadata } from '../transactions'
 import { BaseTransaction } from '../transactions/common'
-import { PseudoTransaction } from '../transactions/transaction'
 
 import { BaseRequest, BaseResponse } from './baseMethod'
 
@@ -42,36 +47,72 @@ export interface TxRequest extends BaseRequest {
   max_ledger?: number
 }
 
+/**
+ * Common properties of transaction responses.
+ *
+ * @category Responses
+ */
+interface BaseTxResult<
+  Version extends APIVersion = typeof DEFAULT_API_VERSION,
+  T extends BaseTransaction = Transaction,
+> {
+  /** The SHA-512 hash of the transaction. */
+  hash: string
+  /**
+   * The Concise Transaction Identifier of the transaction (16-byte hex string)
+   */
+  ctid?: string
+  /** The ledger index of the ledger that includes this transaction. */
+  ledger_index?: number
+  /** Unique hashed string Transaction metadata blob, which describes the results of the transaction.
+   *  Can be undefined if a transaction has not been validated yet. This field is omitted if binary
+   *  binary format is not requested. */
+  meta_blob?: Version extends typeof RIPPLED_API_V2
+    ? TransactionMetadata<T> | string
+    : never
+  /** Transaction metadata, which describes the results of the transaction.
+   *  Can be undefined if a transaction has not been validated yet. */
+  meta?: TransactionMetadata<T> | string
+  /**
+   * If true, this data comes from a validated ledger version; if omitted or.
+   * Set to false, this data is not final.
+   */
+  validated?: boolean
+  /**
+   * The time the transaction was closed, in seconds since the Ripple Epoch.
+   */
+  close_time_iso?: string
+  /**
+   * This number measures the number of seconds since the "Ripple Epoch" of January 1, 2000 (00:00 UTC)
+   */
+  date?: number
+}
+
 /**
  * Response expected from a {@link TxRequest}.
  *
  * @category Responses
  */
-export interface TxResponse<
-  T extends BaseTransaction = Transaction | PseudoTransaction,
-> extends BaseResponse {
-  result: {
-    /** The SHA-512 hash of the transaction. */
-    hash: string
-    /**
-     * The Concise Transaction Identifier of the transaction (16-byte hex string)
-     */
-    ctid?: string
-    /** The ledger index of the ledger that includes this transaction. */
-    ledger_index?: number
-    /** Transaction metadata, which describes the results of the transaction.
-     *  Can be undefined if a transaction has not been validated yet. */
-    meta?: TransactionMetadata | string
-    /**
-     * If true, this data comes from a validated ledger version; if omitted or.
-     * Set to false, this data is not final.
-     */
-    validated?: boolean
-    /**
-     * This number measures the number of seconds since the "Ripple Epoch" of January 1, 2000 (00:00 UTC)
-     */
-    date?: number
-  } & T
+export interface TxResponse<T extends BaseTransaction = Transaction>
+  extends BaseResponse {
+  result: BaseTxResult<typeof RIPPLED_API_V2, T> & { tx_json: T }
+  /**
+   * If true, the server was able to search all of the specified ledger
+   * versions, and the transaction was in none of them. If false, the server did
+   * not have all of the specified ledger versions available, so it is not sure.
+   * If one of them might contain the transaction.
+   */
+  searched_all?: boolean
+}
+
+/**
+ * Response expected from a {@link TxRequest} using API version 1.
+ *
+ * @category ResponsesV1
+ */
+export interface TxV1Response<T extends BaseTransaction = Transaction>
+  extends BaseResponse {
+  result: BaseTxResult<typeof RIPPLED_API_V1, T> & T
   /**
    * If true, the server was able to search all of the specified ledger
    * versions, and the transaction was in none of them. If false, the server did
@@ -80,3 +121,12 @@ export interface TxResponse<
    */
   searched_all?: boolean
 }
+
+/**
+ * Type to map between the API version and the response type.
+ *
+ * @category Responses
+ */
+export type TxVersionResponseMap<
+  Version extends APIVersion = typeof DEFAULT_API_VERSION,
+> = Version extends typeof RIPPLED_API_V1 ? TxV1Response : TxResponse

package/src/models/transactions/AMMClawback.ts

@@ -0,0 +1,120 @@
+import { ValidationError } from '../../errors'
+import { Currency, IssuedCurrency, IssuedCurrencyAmount } from '../common'
+
+import {
+  Account,
+  BaseTransaction,
+  GlobalFlags,
+  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 GlobalFlags {
+  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',
+      )
+    }
+  }
+}