xrpl 1.0.0-mpt-beta → 1.0.3-mpt-beta

package/src/models/methods/ledger.ts

@@ -1,4 +1,5 @@
-import { Ledger } from '../ledger'
+import { APIVersion, DEFAULT_API_VERSION, RIPPLED_API_V1 } from '../common'
+import { Ledger, LedgerV1, LedgerVersionMap } from '../ledger/Ledger'
 import { LedgerEntryFilter } from '../ledger/LedgerEntry'
 import { Transaction, TransactionAndMetadata } from '../transactions'
 import { TransactionMetadata } from '../transactions/metadata'
@@ -207,6 +208,12 @@ export interface LedgerBinary
   transactions?: string[]
 }
 
+export interface LedgerBinaryV1
+  extends Omit<Omit<LedgerV1, 'transactions'>, 'accountState'> {
+  accountState?: string[]
+  transactions?: string[]
+}
+
 interface LedgerResponseBase {
   /** Unique identifying hash of the entire ledger. */
   ledger_hash: string
@@ -231,6 +238,11 @@ interface LedgerResponseResult extends LedgerResponseBase {
   ledger: LedgerBinary
 }
 
+interface LedgerV1ResponseResult extends LedgerResponseBase {
+  /** The complete header data of this {@link Ledger}. */
+  ledger: LedgerBinaryV1
+}
+
 /**
  * Response expected from a {@link LedgerRequest}.
  * This is the default request response, triggered when `expand` and `binary` are both false.
@@ -241,9 +253,31 @@ export interface LedgerResponse extends BaseResponse {
   result: LedgerResponseResult
 }
 
-interface LedgerResponseExpandedResult extends LedgerResponseBase {
+/**
+ * Response expected from a {@link LedgerRequest}.
+ * This is the default request response, triggered when `expand` and `binary` are both false.
+ * This is the response for API version 1.
+ *
+ * @category ResponsesV1
+ */
+export interface LedgerV1Response extends BaseResponse {
+  result: LedgerV1ResponseResult
+}
+
+/**
+ * Type to map between the API version and the response type.
+ *
+ * @category Responses
+ */
+export type LedgerVersionResponseMap<
+  Version extends APIVersion = typeof DEFAULT_API_VERSION,
+> = Version extends typeof RIPPLED_API_V1 ? LedgerV1Response : LedgerResponse
+
+interface LedgerResponseExpandedResult<
+  Version extends APIVersion = typeof DEFAULT_API_VERSION,
+> extends LedgerResponseBase {
   /** The complete header data of this {@link Ledger}. */
-  ledger: Ledger
+  ledger: LedgerVersionMap<Version>
 }
 
 /**
@@ -254,6 +288,8 @@ interface LedgerResponseExpandedResult extends LedgerResponseBase {
  *
  * @category Responses
  */
-export interface LedgerResponseExpanded extends BaseResponse {
-  result: LedgerResponseExpandedResult
+export interface LedgerResponseExpanded<
+  Version extends APIVersion = typeof DEFAULT_API_VERSION,
+> extends BaseResponse {
+  result: LedgerResponseExpandedResult<Version>
 }

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.

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/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/tx.ts

@@ -1,3 +1,9 @@
+import {
+  APIVersion,
+  DEFAULT_API_VERSION,
+  RIPPLED_API_V1,
+  RIPPLED_API_V2,
+} from '../common'
 import { Transaction, TransactionMetadata } from '../transactions'
 import { BaseTransaction } from '../transactions/common'
 
@@ -41,6 +47,47 @@ 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}.
  *
@@ -48,28 +95,7 @@ export interface TxRequest extends BaseRequest {
  */
 export interface TxResponse<T extends BaseTransaction = Transaction>
   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<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
-    /**
-     * This number measures the number of seconds since the "Ripple Epoch" of January 1, 2000 (00:00 UTC)
-     */
-    date?: number
-  } & T
+  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
@@ -78,3 +104,29 @@ export interface TxResponse<T extends BaseTransaction = 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
+   * 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
+}
+
+/**
+ * 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/AMMDeposit.ts

@@ -21,6 +21,7 @@ export enum AMMDepositFlags {
   tfTwoAsset = 0x00100000,
   tfOneAssetLPToken = 0x00200000,
   tfLimitLPToken = 0x00400000,
+  tfTwoAssetIfEmpty = 0x00800000,
 }
 
 export interface AMMDepositFlagsInterface extends GlobalFlags {
@@ -29,6 +30,7 @@ export interface AMMDepositFlagsInterface extends GlobalFlags {
   tfTwoAsset?: boolean
   tfOneAssetLPToken?: boolean
   tfLimitLPToken?: boolean
+  tfTwoAssetIfEmpty?: boolean
 }
 
 /**

package/src/models/transactions/index.ts

@@ -74,6 +74,8 @@ export {
   OfferCreateFlagsInterface,
   OfferCreate,
 } from './offerCreate'
+export { OracleDelete } from './oracleDelete'
+export { OracleSet } from './oracleSet'
 export { PaymentFlags, PaymentFlagsInterface, Payment } from './payment'
 export {
   PaymentChannelClaimFlags,

package/src/models/transactions/metadata.ts

@@ -1,4 +1,4 @@
-import { Amount } from '../common'
+import { Amount, MPTAmount } from '../common'
 
 import { BaseTransaction } from './common'
 import {
@@ -44,6 +44,7 @@ export interface DeletedNode {
   DeletedNode: {
     LedgerEntryType: string
     LedgerIndex: string
+    PreviousFields?: { [field: string]: unknown }
     FinalFields: { [field: string]: unknown }
   }
 }
@@ -82,9 +83,9 @@ export function isDeletedNode(node: Node): node is DeletedNode {
 
 export interface TransactionMetadataBase {
   AffectedNodes: Node[]
-  DeliveredAmount?: Amount
+  DeliveredAmount?: Amount | MPTAmount
   // "unavailable" possible for transactions before 2014-01-20
-  delivered_amount?: Amount | 'unavailable'
+  delivered_amount?: Amount | MPTAmount | 'unavailable'
   TransactionIndex: number
   TransactionResult: string
 }

package/src/models/transactions/oracleDelete.ts

@@ -0,0 +1,32 @@
+import {
+  BaseTransaction,
+  isNumber,
+  validateBaseTransaction,
+  validateRequiredField,
+} from './common'
+
+/**
+ * Delete an Oracle ledger entry.
+ *
+ * @category Transaction Models
+ */
+export interface OracleDelete extends BaseTransaction {
+  TransactionType: 'OracleDelete'
+
+  /**
+   * A unique identifier of the price oracle for the Account.
+   */
+  OracleDocumentID: number
+}
+
+/**
+ * Verify the form and type of a OracleDelete at runtime.
+ *
+ * @param tx - A OracleDelete Transaction.
+ * @throws When the OracleDelete is malformed.
+ */
+export function validateOracleDelete(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'OracleDocumentID', isNumber)
+}

package/src/models/transactions/oracleSet.ts

@@ -0,0 +1,176 @@
+import { ValidationError } from '../../errors'
+import { PriceData } from '../common'
+
+import {
+  BaseTransaction,
+  isNumber,
+  isString,
+  validateBaseTransaction,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
+
+const PRICE_DATA_SERIES_MAX_LENGTH = 10
+const SCALE_MAX = 10
+
+/**
+ * Creates a new Oracle ledger entry or updates the fields of an existing one, using the Oracle ID.
+ *
+ * The oracle provider must complete these steps before submitting this transaction:
+ * 1. Create or own the XRPL account in the Owner field and have enough XRP to meet the reserve and transaction fee requirements.
+ * 2. Publish the XRPL account public key, so it can be used for verification by dApps.
+ * 3. Publish a registry of available price oracles with their unique OracleDocumentID.
+ *
+ * @category Transaction Models
+ */
+export interface OracleSet extends BaseTransaction {
+  TransactionType: 'OracleSet'
+
+  /**
+   * A unique identifier of the price oracle for the Account.
+   */
+  OracleDocumentID: number
+
+  /**
+   * The time the data was last updated, represented as a unix timestamp in seconds.
+   */
+  LastUpdateTime: number
+
+  /**
+   * An array of up to 10 PriceData objects, each representing the price information
+   * for a token pair. More than five PriceData objects require two owner reserves.
+   */
+  PriceDataSeries: PriceData[]
+
+  /**
+   * An arbitrary value that identifies an oracle provider, such as Chainlink, Band,
+   * or DIA. This field is a string, up to 256 ASCII hex encoded characters (0x20-0x7E).
+   * This field is required when creating a new Oracle ledger entry, but is optional for updates.
+   */
+  Provider?: string
+
+  /**
+   * An optional Universal Resource Identifier to reference price data off-chain. This field is limited to 256 bytes.
+   */
+  URI?: string
+
+  /**
+   * Describes the type of asset, such as "currency", "commodity", or "index". This field is a string, up to 16 ASCII
+   * hex encoded characters (0x20-0x7E). This field is required when creating a new Oracle ledger entry, but is optional
+   * for updates.
+   */
+  AssetClass?: string
+}
+
+/**
+ * Verify the form and type of a OracleSet at runtime.
+ *
+ * @param tx - A OracleSet Transaction.
+ * @throws When the OracleSet is malformed.
+ */
+// eslint-disable-next-line max-lines-per-function -- necessary to validate many fields
+export function validateOracleSet(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'OracleDocumentID', isNumber)
+
+  validateRequiredField(tx, 'LastUpdateTime', isNumber)
+
+  validateOptionalField(tx, 'Provider', isString)
+
+  validateOptionalField(tx, 'URI', isString)
+
+  validateOptionalField(tx, 'AssetClass', isString)
+
+  // eslint-disable-next-line max-lines-per-function -- necessary to validate many fields
+  validateRequiredField(tx, 'PriceDataSeries', (value) => {
+    if (!Array.isArray(value)) {
+      throw new ValidationError('OracleSet: PriceDataSeries must be an array')
+    }
+
+    if (value.length > PRICE_DATA_SERIES_MAX_LENGTH) {
+      throw new ValidationError(
+        `OracleSet: PriceDataSeries must have at most ${PRICE_DATA_SERIES_MAX_LENGTH} PriceData objects`,
+      )
+    }
+
+    // TODO: add support for handling inner objects easier (similar to validateRequiredField/validateOptionalField)
+    for (const priceData of value) {
+      if (typeof priceData !== 'object') {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must be an array of objects',
+        )
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+      if (priceData.PriceData == null) {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must have a `PriceData` object',
+        )
+      }
+
+      // check if priceData only has PriceData
+      if (Object.keys(priceData).length !== 1) {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must only have a single PriceData object',
+        )
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+      if (typeof priceData.PriceData.BaseAsset !== 'string') {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must have a `BaseAsset` string',
+        )
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+      if (typeof priceData.PriceData.QuoteAsset !== 'string') {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must have a `QuoteAsset` string',
+        )
+      }
+
+      // Either AssetPrice and Scale are both present or both excluded
+      if (
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        (priceData.PriceData.AssetPrice == null) !==
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        (priceData.PriceData.Scale == null)
+      ) {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must have both `AssetPrice` and `Scale` if any are present',
+        )
+      }
+
+      if (
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        'AssetPrice' in priceData.PriceData &&
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        !isNumber(priceData.PriceData.AssetPrice)
+      ) {
+        throw new ValidationError('OracleSet: invalid field AssetPrice')
+      }
+
+      if (
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        'Scale' in priceData.PriceData &&
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        !isNumber(priceData.PriceData.Scale)
+      ) {
+        throw new ValidationError('OracleSet: invalid field Scale')
+      }
+
+      if (
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        priceData.PriceData.Scale < 0 ||
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        priceData.PriceData.Scale > SCALE_MAX
+      ) {
+        throw new ValidationError(
+          `OracleSet: Scale must be in range 0-${SCALE_MAX}`,
+        )
+      }
+    }
+    return true
+  })
+}

package/src/models/transactions/payment.ts

@@ -1,5 +1,5 @@
 import { ValidationError } from '../../errors'
-import { Amount, Path } from '../common'
+import { Amount, Path, MPTAmount } from '../common'
 import { isFlagEnabled } from '../utils'
 
 import {
@@ -26,7 +26,7 @@ export enum PaymentFlags {
    * This is intended to force the transaction to take arbitrage opportunities.
    * Most clients do not need this.
    */
-  tfNoDirectRipple = 0x00010000,
+  tfNoRippleDirect = 0x00010000,
   /**
    * If the specified Amount cannot be sent without spending more than SendMax,
    * reduce the received amount instead of failing outright. See Partial.
@@ -88,7 +88,7 @@ export interface PaymentFlagsInterface extends GlobalFlags {
    * This is intended to force the transaction to take arbitrage opportunities.
    * Most clients do not need this.
    */
-  tfNoDirectRipple?: boolean
+  tfNoRippleDirect?: boolean
   /**
    * If the specified Amount cannot be sent without spending more than SendMax,
    * reduce the received amount instead of failing outright. See Partial.
@@ -116,7 +116,7 @@ export interface Payment extends BaseTransaction {
    * names MUST be lower-case. If the tfPartialPayment flag is set, deliver up
    * to this amount instead.
    */
-  Amount: Amount
+  Amount: Amount | MPTAmount
   /** The unique address of the account receiving the payment. */
   Destination: Account
   /**
@@ -153,8 +153,8 @@ export interface Payment extends BaseTransaction {
 }
 
 export interface PaymentMetadata extends TransactionMetadataBase {
-  DeliveredAmount?: Amount
-  delivered_amount?: Amount | 'unavailable'
+  DeliveredAmount?: Amount | MPTAmount
+  delivered_amount?: Amount | MPTAmount | 'unavailable'
 }
 
 /**