xrpl 3.0.0 → 4.0.0-mpt-beta

package/src/client/partialPayment.ts

@@ -2,21 +2,27 @@ import BigNumber from 'bignumber.js'
 import { decode } from 'ripple-binary-codec'
 
 import type {
-  AccountTxResponse,
   TransactionEntryResponse,
   TransactionStream,
   TxResponse,
 } from '..'
-import type { Amount } from '../models/common'
-import type { RequestResponseMap } from '../models/methods'
+import type { Amount, IssuedCurrency,APIVersion, DEFAULT_API_VERSION , MPTAmount } from '../models/common'
+import type {
+  AccountTxTransaction,
+  RequestResponseMap,
+} from '../models/methods'
+import { AccountTxVersionResponseMap } from '../models/methods/accountTx'
 import { BaseRequest, BaseResponse } from '../models/methods/baseMethod'
-import { PaymentFlags, Transaction } from '../models/transactions'
+import { PaymentFlags, Transaction, isMPTAmount } from '../models/transactions'
 import type { TransactionMetadata } from '../models/transactions/metadata'
 import { isFlagEnabled } from '../models/utils'
 
 const WARN_PARTIAL_PAYMENT_CODE = 2001
 
-function amountsEqual(amt1: Amount, amt2: Amount): boolean {
+function amountsEqual(
+  amt1: Amount | MPTAmount,
+  amt2: Amount | MPTAmount,
+): boolean {
   if (typeof amt1 === 'string' && typeof amt2 === 'string') {
     return amt1 === amt2
   }
@@ -25,12 +31,26 @@ function amountsEqual(amt1: Amount, amt2: Amount): boolean {
     return false
   }
 
+  if (isMPTAmount(amt1) && isMPTAmount(amt2)) {
+    const aValue = new BigNumber(amt1.value)
+    const bValue = new BigNumber(amt2.value)
+
+    return (
+      (amt1 as MPTAmount).mpt_issuance_id ===
+        (amt2 as MPTAmount).mpt_issuance_id && aValue.isEqualTo(bValue)
+    )
+  }
+
+  if (isMPTAmount(amt1) || isMPTAmount(amt2)) {
+    return false
+  }
+
   const aValue = new BigNumber(amt1.value)
   const bValue = new BigNumber(amt2.value)
 
   return (
-    amt1.currency === amt2.currency &&
-    amt1.issuer === amt2.issuer &&
+    (amt1 as IssuedCurrency).currency === (amt2 as IssuedCurrency).currency &&
+    (amt1 as IssuedCurrency).issuer === (amt2 as IssuedCurrency).issuer &&
     aValue.isEqualTo(bValue)
   )
 }
@@ -63,7 +83,10 @@ function isPartialPayment(
   }
 
   const delivered = meta.delivered_amount
-  const amount = tx.Amount
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- DeliverMax is a valid field on Payment response
+  // @ts-expect-error -- DeliverMax is a valid field on Payment response
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- DeliverMax is a valid field on Payment response
+  const amount = tx.DeliverMax
 
   if (delivered === undefined) {
     return false
@@ -73,23 +96,36 @@ function isPartialPayment(
 }
 
 function txHasPartialPayment(response: TxResponse): boolean {
-  return isPartialPayment(response.result, response.result.meta)
+  return isPartialPayment(response.result.tx_json, response.result.meta)
 }
 
 function txEntryHasPartialPayment(response: TransactionEntryResponse): boolean {
   return isPartialPayment(response.result.tx_json, response.result.metadata)
 }
 
-function accountTxHasPartialPayment(response: AccountTxResponse): boolean {
+function accountTxHasPartialPayment<
+  Version extends APIVersion = typeof DEFAULT_API_VERSION,
+>(response: AccountTxVersionResponseMap<Version>): boolean {
   const { transactions } = response.result
-  const foo = transactions.some((tx) => isPartialPayment(tx.tx, tx.meta))
+  const foo = transactions.some((tx) => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- required to check API version model
+    if (tx.tx_json != null) {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- use API v2 model
+      const transaction = tx as AccountTxTransaction
+      return isPartialPayment(transaction.tx_json, transaction.meta)
+    }
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- use API v1 model
+    const transaction = tx as AccountTxTransaction<1>
+    return isPartialPayment(transaction.tx, transaction.meta)
+  })
   return foo
 }
 
-function hasPartialPayment<R extends BaseRequest, T = RequestResponseMap<R>>(
-  command: string,
-  response: T,
-): boolean {
+function hasPartialPayment<
+  R extends BaseRequest,
+  V extends APIVersion = typeof DEFAULT_API_VERSION,
+  T = RequestResponseMap<R, V>,
+>(command: string, response: T): boolean {
   /* eslint-disable @typescript-eslint/consistent-type-assertions -- Request type is known at runtime from command */
   switch (command) {
     case 'tx':
@@ -97,7 +133,9 @@ function hasPartialPayment<R extends BaseRequest, T = RequestResponseMap<R>>(
     case 'transaction_entry':
       return txEntryHasPartialPayment(response as TransactionEntryResponse)
     case 'account_tx':
-      return accountTxHasPartialPayment(response as AccountTxResponse)
+      return accountTxHasPartialPayment(
+        response as AccountTxVersionResponseMap<V>,
+      )
     default:
       return false
   }
@@ -112,7 +150,7 @@ function hasPartialPayment<R extends BaseRequest, T = RequestResponseMap<R>>(
  */
 export function handlePartialPayment<
   R extends BaseRequest,
-  T = RequestResponseMap<R>,
+  T = RequestResponseMap<R, APIVersion>,
 >(command: string, response: T): void {
   if (hasPartialPayment(command, response)) {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- We are checking dynamically and safely.

package/src/models/common/index.ts

@@ -1,3 +1,7 @@
+export const RIPPLED_API_V1 = 1
+export const RIPPLED_API_V2 = 2
+export const DEFAULT_API_VERSION = RIPPLED_API_V2
+export type APIVersion = typeof RIPPLED_API_V1 | typeof RIPPLED_API_V2
 export type LedgerIndex = number | ('validated' | 'closed' | 'current')
 
 export interface XRP {
@@ -16,6 +20,11 @@ export interface IssuedCurrencyAmount extends IssuedCurrency {
   value: string
 }
 
+export interface MPTAmount {
+  mpt_issuance_id: string
+  value: string
+}
+
 export type Amount = IssuedCurrencyAmount | string
 
 export interface Balance {
@@ -104,6 +113,10 @@ export interface ResponseOnlyTxInfo {
    * The sequence number of the ledger that included this transaction.
    */
   ledger_index?: number
+  /**
+   * The hash of the ledger included this transaction.
+   */
+  ledger_hash?: string
   /**
    * @deprecated Alias for ledger_index.
    */
@@ -155,3 +168,36 @@ export interface XChainBridge {
   IssuingChainDoor: string
   IssuingChainIssue: Currency
 }
+
+/**
+ * A PriceData object represents the price information for a token pair.
+ *
+ */
+export interface PriceData {
+  PriceData: {
+    /**
+     * The primary asset in a trading pair. Any valid identifier, such as a stock symbol, bond CUSIP, or currency code is allowed.
+     * For example, in the BTC/USD pair, BTC is the base asset; in 912810RR9/BTC, 912810RR9 is the base asset.
+     */
+    BaseAsset: string
+
+    /**
+     * The quote asset in a trading pair. The quote asset denotes the price of one unit of the base asset. For example, in the
+     * BTC/USD pair,BTC is the base asset; in 912810RR9/BTC, 912810RR9 is the base asset.
+     */
+    QuoteAsset: string
+
+    /**
+     * The asset price after applying the Scale precision level. It's not included if the last update transaction didn't include
+     * the BaseAsset/QuoteAsset pair.
+     */
+    AssetPrice?: number | string
+
+    /**
+     * The scaling factor to apply to an asset price. For example, if Scale is 6 and original price is 0.155, then the scaled
+     * price is 155000. Valid scale ranges are 0-10. It's not included if the last update transaction didn't include the
+     * BaseAsset/QuoteAsset pair.
+     */
+    Scale?: number
+  }
+}

package/src/models/index.ts

@@ -10,6 +10,7 @@ export * as LedgerEntry from './ledger'
 export {
   setTransactionFlagsToNumber,
   parseAccountRootFlags,
+  parseTransactionFlags,
 } from './utils/flags'
 export * from './methods'
 export * from './transactions'

package/src/models/ledger/AMM.ts

@@ -1,6 +1,6 @@
 import { AuthAccount, Currency, IssuedCurrencyAmount } from '../common'
 
-import { BaseLedgerEntry, MissingPreviousTxnID } from './BaseLedgerEntry'
+import { BaseLedgerEntry, HasOptionalPreviousTxnID } from './BaseLedgerEntry'
 
 export interface VoteSlot {
   VoteEntry: {
@@ -15,7 +15,7 @@ export interface VoteSlot {
  *
  * @category Ledger Entries
  */
-export default interface AMM extends BaseLedgerEntry, MissingPreviousTxnID {
+export default interface AMM extends BaseLedgerEntry, HasOptionalPreviousTxnID {
   LedgerEntryType: 'AMM'
   /**
    * The address of the special account that holds this AMM's assets.

package/src/models/ledger/Amendments.ts

@@ -1,4 +1,4 @@
-import { BaseLedgerEntry, MissingPreviousTxnID } from './BaseLedgerEntry'
+import { BaseLedgerEntry, HasOptionalPreviousTxnID } from './BaseLedgerEntry'
 
 /**
  * The unique id for the Amendments object https://xrpl.org/amendments-object.html#amendments-id-format
@@ -26,7 +26,7 @@ export interface Majority {
  */
 export default interface Amendments
   extends BaseLedgerEntry,
-    MissingPreviousTxnID {
+    HasOptionalPreviousTxnID {
   LedgerEntryType: 'Amendments'
   /**
    * Array of 256-bit amendment IDs for all currently-enabled amendments. If

package/src/models/ledger/BaseLedgerEntry.ts

@@ -15,13 +15,17 @@ export interface HasPreviousTxnID {
   PreviousTxnLgrSeq: number
 }
 
-export interface MissingPreviousTxnID {
+export interface HasOptionalPreviousTxnID {
   /**
-   * This field is missing on this object but is present on most other returned objects.
+   * The identifying hash of the transaction that most recently modified this
+   * object. This field was added in the `fixPreviousTxnID` amendment, so it
+   * may not be present in every object.
    */
-  PreviousTxnID: never
+  PreviousTxnID?: string
   /**
-   * This field is missing on this object but is present on most other returned objects.
+   * The index of the ledger that contains the transaction that most recently
+   * modified this object. This field was added in the `fixPreviousTxnID`
+   * amendment, so it may not be present in every object.
    */
-  PreviousTxnLgrSeq: never
+  PreviousTxnLgrSeq?: number
 }

package/src/models/ledger/DirectoryNode.ts

@@ -1,4 +1,4 @@
-import { BaseLedgerEntry, MissingPreviousTxnID } from './BaseLedgerEntry'
+import { BaseLedgerEntry, HasOptionalPreviousTxnID } from './BaseLedgerEntry'
 
 /**
  * The DirectoryNode object type provides a list of links to other objects in
@@ -8,7 +8,7 @@ import { BaseLedgerEntry, MissingPreviousTxnID } from './BaseLedgerEntry'
  */
 export default interface DirectoryNode
   extends BaseLedgerEntry,
-    MissingPreviousTxnID {
+    HasOptionalPreviousTxnID {
   LedgerEntryType: 'DirectoryNode'
   /**
    * A bit-map of boolean flags enabled for this directory. Currently, the

package/src/models/ledger/FeeSettings.ts

@@ -1,4 +1,4 @@
-import { BaseLedgerEntry, MissingPreviousTxnID } from './BaseLedgerEntry'
+import { BaseLedgerEntry, HasOptionalPreviousTxnID } from './BaseLedgerEntry'
 
 /**
  * The unique id for the FeeSettings object https://xrpl.org/feesettings.html#feesettings-id-format
@@ -26,7 +26,9 @@ export interface FeeSettingsPostAmendmentFields {
   ReserveIncrementDrops: string
 }
 
-export interface FeeSettingsBase extends BaseLedgerEntry, MissingPreviousTxnID {
+export interface FeeSettingsBase
+  extends BaseLedgerEntry,
+    HasOptionalPreviousTxnID {
   LedgerEntryType: 'FeeSettings'
   /**
    * A bit-map of boolean flags for this object. No flags are defined for this type.

package/src/models/ledger/Ledger.ts

@@ -1,14 +1,14 @@
+import { APIVersion, DEFAULT_API_VERSION, RIPPLED_API_V1 } from '../common'
 import { Transaction, TransactionMetadata } from '../transactions'
 
 import { LedgerEntry } from './LedgerEntry'
 
 /**
- * A ledger is a block of transactions and shared state data. It has a unique
- * header that describes its contents using cryptographic hashes.
+ * Common properties for ledger entries.
  *
  * @category Ledger Entries
  */
-export default interface Ledger {
+interface BaseLedger {
   /** The SHA-512Half of this ledger's state tree information. */
   account_hash: string
   /** All the state information in this ledger. Admin only. */
@@ -38,11 +38,6 @@ export default interface Ledger {
    * for this ledger and all its contents.
    */
   ledger_hash: string
-  /**
-   * The ledger index of the ledger. Some API methods display this as a quoted
-   * integer; some display it as a native JSON number.
-   */
-  ledger_index: string
   /** The approximate time at which the previous ledger was closed. */
   parent_close_time: number
   /**
@@ -61,5 +56,47 @@ export default interface Ledger {
    * either JSON or binary depending on whether the request specified binary
    * as true.
    */
-  transactions?: Array<Transaction & { metaData?: TransactionMetadata }>
+  transactions?: Array<
+    Transaction & {
+      hash: string
+      metaData?: TransactionMetadata
+    }
+  >
+}
+
+/**
+ * A ledger is a block of transactions and shared state data. It has a unique
+ * header that describes its contents using cryptographic hashes.
+ *
+ * @category Ledger Entries
+ */
+export interface Ledger extends BaseLedger {
+  /**
+   * The ledger index of the ledger. Represented as a number.
+   */
+  ledger_index: number
 }
+
+/**
+ * A ledger is a block of transactions and shared state data. It has a unique
+ * header that describes its contents using cryptographic hashes. This is used
+ * in api_version 1.
+ *
+ * @category Ledger Entries
+ */
+export interface LedgerV1 extends BaseLedger {
+  /**
+   * The ledger index of the ledger. Some API methods display this as a quoted
+   * integer; some display it as a number.
+   */
+  ledger_index: string
+}
+
+/**
+ * Type to map between the API version and the Ledger type.
+ *
+ * @category Responses
+ */
+export type LedgerVersionMap<
+  Version extends APIVersion = typeof DEFAULT_API_VERSION,
+> = Version extends typeof RIPPLED_API_V1 ? LedgerV1 : Ledger

package/src/models/ledger/LedgerEntry.ts

@@ -10,6 +10,7 @@ import FeeSettings from './FeeSettings'
 import LedgerHashes from './LedgerHashes'
 import NegativeUNL from './NegativeUNL'
 import Offer from './Offer'
+import Oracle from './Oracle'
 import PayChannel from './PayChannel'
 import RippleState from './RippleState'
 import SignerList from './SignerList'
@@ -30,6 +31,7 @@ type LedgerEntry =
   | LedgerHashes
   | NegativeUNL
   | Offer
+  | Oracle
   | PayChannel
   | RippleState
   | SignerList
@@ -49,9 +51,12 @@ type LedgerEntryFilter =
   | 'escrow'
   | 'fee'
   | 'hashes'
+  | 'mpt_issuance'
+  | 'mptoken'
   | 'nft_offer'
   | 'nft_page'
   | 'offer'
+  | 'oracle'
   | 'payment_channel'
   | 'signer_list'
   | 'state'

package/src/models/ledger/LedgerHashes.ts

@@ -1,4 +1,4 @@
-import { BaseLedgerEntry, MissingPreviousTxnID } from './BaseLedgerEntry'
+import { BaseLedgerEntry } from './BaseLedgerEntry'
 
 /**
  * The LedgerHashes objects exist to make it possible to look up a previous
@@ -7,9 +7,7 @@ import { BaseLedgerEntry, MissingPreviousTxnID } from './BaseLedgerEntry'
  *
  * @category Ledger Entries
  */
-export default interface LedgerHashes
-  extends BaseLedgerEntry,
-    MissingPreviousTxnID {
+export default interface LedgerHashes extends BaseLedgerEntry {
   LedgerEntryType: 'LedgerHashes'
   /** The Ledger Index of the last entry in this object's Hashes array. */
   LastLedgerSequence?: number

package/src/models/ledger/MPToken.ts

@@ -0,0 +1,12 @@
+import { MPTAmount } from '../common'
+
+import { BaseLedgerEntry, HasPreviousTxnID } from './BaseLedgerEntry'
+
+export interface MPToken extends BaseLedgerEntry, HasPreviousTxnID {
+  LedgerEntryType: 'MPToken'
+  MPTokenIssuanceID: string
+  MPTAmount: MPTAmount
+  LockedAmount?: MPTAmount
+  Flags: number
+  OwnerNode?: string
+}

package/src/models/ledger/MPTokenIssuance.ts

@@ -0,0 +1,14 @@
+import { BaseLedgerEntry, HasPreviousTxnID } from './BaseLedgerEntry'
+
+export interface MPTokenIssuance extends BaseLedgerEntry, HasPreviousTxnID {
+  LedgerEntryType: 'MPTokenIssuance'
+  Flags: number
+  Issuer: string
+  AssetScale?: number
+  MaximumAmount?: string
+  OutstandingAmount: string
+  LockedAmount?: string
+  TransferFee?: number
+  MPTokenMetadata?: string
+  OwnerNode?: string
+}

package/src/models/ledger/NegativeUNL.ts

@@ -1,4 +1,4 @@
-import { BaseLedgerEntry, MissingPreviousTxnID } from './BaseLedgerEntry'
+import { BaseLedgerEntry, HasOptionalPreviousTxnID } from './BaseLedgerEntry'
 
 /**
  * The unique id for the nUNL object https://xrpl.org/negativeunl.html#negativeunl-id-format
@@ -14,7 +14,7 @@ export const NEGATIVE_UNL_ID =
  */
 export default interface NegativeUNL
   extends BaseLedgerEntry,
-    MissingPreviousTxnID {
+    HasOptionalPreviousTxnID {
   LedgerEntryType: 'NegativeUNL'
   /**
    * A list of trusted validators that are currently disabled.

package/src/models/ledger/Oracle.ts

@@ -0,0 +1,43 @@
+import { PriceData } from '../common'
+
+import { BaseLedgerEntry, HasPreviousTxnID } from './BaseLedgerEntry'
+
+/**
+ * The Oracle object type describes a single Price Oracle instance.
+ *
+ * @category Ledger Entries
+ */
+export default interface Oracle extends BaseLedgerEntry, HasPreviousTxnID {
+  LedgerEntryType: 'Oracle'
+
+  /**
+   * The time the data was last updated, represented as a unix timestamp in seconds.
+   */
+  LastUpdateTime: number
+
+  /**
+   * The XRPL account with update and delete privileges for the oracle.
+   */
+  Owner: string
+
+  /**
+   * Describes the type of asset, such as "currency", "commodity", or "index".
+   */
+  AssetClass: string
+
+  /**
+   * The oracle provider, such as Chainlink, Band, or DIA.
+   */
+  Provider: string
+
+  /**
+   * An array of up to 10 PriceData objects.
+   */
+  PriceDataSeries: PriceData[]
+
+  /**
+   * A bit-map of boolean flags. No flags are defined for the Oracle object
+   * type, so this value is always 0.
+   */
+  Flags: 0
+}

package/src/models/ledger/RippleState.ts

@@ -75,4 +75,6 @@ export enum RippleStateFlags {
   lsfLowFreeze = 0x00400000,
   // True, high side has set freeze flag
   lsfHighFreeze = 0x00800000,
+  // True, trust line to AMM. Used by client apps to identify payments via AMM.
+  lsfAMMNode = 0x01000000,
 }

package/src/models/ledger/index.ts

@@ -15,13 +15,16 @@ import FeeSettings, {
   FeeSettingsPostAmendmentFields,
   FEE_SETTINGS_ID,
 } from './FeeSettings'
-import Ledger from './Ledger'
+import { Ledger, LedgerV1 } from './Ledger'
 import { LedgerEntry, LedgerEntryFilter } from './LedgerEntry'
 import LedgerHashes from './LedgerHashes'
 import NegativeUNL, { NEGATIVE_UNL_ID } from './NegativeUNL'
+import { MPTokenIssuance } from './MPTokenIssuance'
+import { MPToken } from './MPToken'
 import { NFTokenOffer } from './NFTokenOffer'
 import { NFToken, NFTokenPage } from './NFTokenPage'
 import Offer, { OfferFlags } from './Offer'
+import Oracle from './Oracle'
 import PayChannel from './PayChannel'
 import RippleState, { RippleStateFlags } from './RippleState'
 import SignerList, { SignerListFlags } from './SignerList'
@@ -47,17 +50,21 @@ export {
   FeeSettingsPreAmendmentFields,
   FeeSettingsPostAmendmentFields,
   Ledger,
+  LedgerV1,
   LedgerEntryFilter,
   LedgerEntry,
   LedgerHashes,
   Majority,
   NEGATIVE_UNL_ID,
   NegativeUNL,
+  MPTokenIssuance,
+  MPToken,
   NFTokenOffer,
   NFTokenPage,
   NFToken,
   Offer,
   OfferFlags,
+  Oracle,
   PayChannel,
   RippleState,
   RippleStateFlags,

package/src/models/methods/accountChannels.ts

@@ -1,17 +1,80 @@
 import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
 
+/**
+ * Represents a payment channel in the XRP Ledger.
+ */
 export interface Channel {
+  /** The owner of the channel, as an Address. */
   account: string
+
+  /** The total amount of XRP, in drops allocated to this channel. */
   amount: string
+
+  /**
+   * The total amount of XRP, in drops, paid out from this channel,
+   * as of the ledger version used. (You can calculate the amount of
+   * XRP left in the channel by subtracting balance from amount.)
+   */
   balance: string
+
+  /**
+   * A unique ID for this channel, as a 64-character hexadecimal string.
+   * This is also the ID of the channel object in the ledger's state data.
+   */
   channel_id: string
+
+  /**
+   * The destination account of the channel, as an Address.
+   * Only this account can receive the XRP in the channel while it is open.
+   */
   destination_account: string
+
+  /**
+   * The number of seconds the payment channel must stay open after the owner
+   * of the channel requests to close it.
+   */
   settle_delay: number
+
+  /**
+   * The public key for the payment channel in the XRP Ledger's base58 format.
+   * Signed claims against this channel must be redeemed with the matching key pair.
+   */
   public_key?: string
+
+  /**
+   * The public key for the payment channel in hexadecimal format, if one was
+   * specified at channel creation. Signed claims against this channel must be
+   * redeemed with the matching key pair.
+   */
   public_key_hex?: string
+
+  /**
+   * Time, in seconds since the Ripple Epoch, when this channel is set to expire.
+   * This expiration date is mutable. If this is before the close time of the most
+   * recent validated ledger, the channel is expired.
+   */
   expiration?: number
+
+  /**
+   * Time, in seconds since the Ripple Epoch, of this channel's immutable expiration,
+   * if one was specified at channel creation. If this is before the close time of the
+   * most recent validated ledger, the channel is expired.
+   */
   cancel_after?: number
-  source_tab?: number
+
+  /**
+   * A 32-bit unsigned integer to use as a source tag for payments through this payment channel,
+   * if one was specified at channel creation. This indicates the payment channel's originator or
+   * other purpose at the source account. Conventionally, if you bounce payments from this channel,
+   * you should specify this value in the DestinationTag of the return payment.
+   */
+  source_tag?: number
+
+  /**
+   * A 32-bit unsigned integer to use as a destination tag for payments through this channel,
+   * if one was specified at channel creation. This indicates the payment channel's beneficiary
+   * or other purpose at the destination account.
+   */
   destination_tag?: number
 }