xrpl 2.12.0 → 3.0.0-beta.0

package/src/models/ledger/XChainOwnedClaimID.ts

@@ -2,7 +2,7 @@ import { Amount } from 'ripple-binary-codec/dist/types'
 
 import { XChainBridge } from '../common'
 
-import BaseLedgerEntry from './BaseLedgerEntry'
+import { BaseLedgerEntry, HasPreviousTxnID } from './BaseLedgerEntry'
 
 /**
  * An XChainOwnedClaimID object represents one cross-chain transfer of value
@@ -11,7 +11,9 @@ import BaseLedgerEntry from './BaseLedgerEntry'
  *
  * @category Ledger Entries
  */
-export default interface XChainOwnedClaimID extends BaseLedgerEntry {
+export default interface XChainOwnedClaimID
+  extends BaseLedgerEntry,
+    HasPreviousTxnID {
   LedgerEntryType: 'XChainOwnedClaimID'
 
   /** The account that checked out this unique claim ID value. */
@@ -76,14 +78,4 @@ export default interface XChainOwnedClaimID extends BaseLedgerEntry {
    * object, in case the directory consists of multiple pages.
    */
   OwnerNode: string
-  /**
-   * The identifying hash of the transaction that most recently modified this
-   * object.
-   */
-  PreviousTxnID: string
-  /**
-   * The index of the ledger that contains the transaction that most recently
-   * modified this object.
-   */
-  PreviousTxnLgrSeq: number
 }

package/src/models/ledger/XChainOwnedCreateAccountClaimID.ts

@@ -1,6 +1,6 @@
 import { XChainBridge } from '../common'
 
-import BaseLedgerEntry from './BaseLedgerEntry'
+import { BaseLedgerEntry, HasPreviousTxnID } from './BaseLedgerEntry'
 
 /**
  * The XChainOwnedCreateAccountClaimID ledger object is used to collect attestations
@@ -9,7 +9,8 @@ import BaseLedgerEntry from './BaseLedgerEntry'
  * @category Ledger Entries
  */
 export default interface XChainOwnedCreateAccountClaimID
-  extends BaseLedgerEntry {
+  extends BaseLedgerEntry,
+    HasPreviousTxnID {
   LedgerEntryType: 'XChainOwnedCreateAccountClaimID'
 
   /** The account that owns this object. */
@@ -61,14 +62,4 @@ export default interface XChainOwnedCreateAccountClaimID
    * object, in case the directory consists of multiple pages.
    */
   OwnerNode: string
-  /**
-   * The identifying hash of the transaction that most recently modified this
-   * object.
-   */
-  PreviousTxnID: string
-  /**
-   * The index of the ledger that contains the transaction that most recently
-   * modified this object.
-   */
-  PreviousTxnLgrSeq: number
 }

package/src/models/ledger/index.ts

@@ -15,7 +15,7 @@ import FeeSettings, {
   FEE_SETTINGS_ID,
 } from './FeeSettings'
 import Ledger from './Ledger'
-import LedgerEntry from './LedgerEntry'
+import { LedgerEntry, LedgerEntryFilter } from './LedgerEntry'
 import LedgerHashes from './LedgerHashes'
 import NegativeUNL, { NEGATIVE_UNL_ID } from './NegativeUNL'
 import { NFTokenOffer } from './NFTokenOffer'
@@ -45,6 +45,7 @@ export {
   FeeSettingsPreAmendmentFields,
   FeeSettingsPostAmendmentFields,
   Ledger,
+  LedgerEntryFilter,
   LedgerEntry,
   LedgerHashes,
   Majority,

package/src/models/methods/accountObjects.ts

@@ -1,35 +1,12 @@
-import {
-  AMM,
-  Bridge,
-  Check,
-  DepositPreauth,
-  Escrow,
-  Offer,
-  PayChannel,
-  RippleState,
-  SignerList,
-  Ticket,
-  XChainOwnedClaimID,
-  XChainOwnedCreateAccountClaimID,
-} from '../ledger'
+import { Amendments, FeeSettings, LedgerHashes } from '../ledger'
+import { LedgerEntry, LedgerEntryFilter } from '../ledger/LedgerEntry'
 
 import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
 
-export type AccountObjectType =
-  | 'amm'
-  | 'bridge'
-  | 'check'
-  | 'deposit_preauth'
-  | 'escrow'
-  | 'nft_offer'
-  | 'offer'
-  | 'payment_channel'
-  | 'signer_list'
-  | 'state'
-  | 'ticket'
-  | 'xchain_owned_create_account_claim_id'
-  | 'xchain_owned_claim_id'
-
+export type AccountObjectType = Exclude<
+  LedgerEntryFilter,
+  'amendments' | 'fee' | 'hashes'
+>
 /**
  * The account_objects command returns the raw ledger format for all objects
  * owned by an account. For a higher-level view of an account's trust lines and
@@ -46,8 +23,6 @@ export interface AccountObjectsRequest
   account: string
   /**
    * If included, filter results to include only this type of ledger object.
-   * The valid types are: Check , DepositPreauth, Escrow, Offer, PayChannel,
-   * SignerList, Ticket, and RippleState (trust line).
    */
   type?: AccountObjectType
   /**
@@ -71,19 +46,10 @@ export interface AccountObjectsRequest
  * Account Objects can be a Check, a DepositPreauth, an Escrow, an Offer, a
  * PayChannel, a SignerList, a Ticket, or a RippleState.
  */
-export type AccountObject =
-  | AMM
-  | Bridge
-  | Check
-  | DepositPreauth
-  | Escrow
-  | Offer
-  | PayChannel
-  | SignerList
-  | RippleState
-  | Ticket
-  | XChainOwnedClaimID
-  | XChainOwnedCreateAccountClaimID
+export type AccountObject = Exclude<
+  LedgerEntry,
+  Amendments | FeeSettings | LedgerHashes
+>
 
 /**
  * Response expected from an {@link AccountObjectsRequest}.

package/src/models/methods/index.ts

@@ -1,3 +1,4 @@
+/* eslint-disable no-inline-comments -- Necessary for important note */
 /* eslint-disable max-lines -- There is a lot to export */
 import {
   AccountChannelsRequest,
@@ -71,6 +72,11 @@ import {
   LedgerQueueData,
   LedgerRequest,
   LedgerResponse,
+  LedgerRequestExpandedTransactionsOnly,
+  LedgerResponseExpanded,
+  LedgerRequestExpandedAccountsAndTransactions,
+  LedgerRequestExpandedAccountsOnly,
+  LedgerRequestExpandedTransactionsBinary,
 } from './ledger'
 import { LedgerClosedRequest, LedgerClosedResponse } from './ledgerClosed'
 import { LedgerCurrentRequest, LedgerCurrentResponse } from './ledgerCurrent'
@@ -253,6 +259,175 @@ type Response =
   // AMM methods
   | AMMInfoResponse
 
+export type RequestResponseMap<T> = T extends AccountChannelsRequest
+  ? AccountChannelsResponse
+  : T extends AccountCurrenciesRequest
+  ? AccountCurrenciesResponse
+  : T extends AccountInfoRequest
+  ? AccountInfoResponse
+  : T extends AccountLinesRequest
+  ? AccountLinesResponse
+  : T extends AccountNFTsRequest
+  ? AccountNFTsResponse
+  : T extends AccountObjectsRequest
+  ? AccountObjectsResponse
+  : T extends AccountOffersRequest
+  ? AccountOffersResponse
+  : T extends AccountTxRequest
+  ? AccountTxResponse
+  : T extends AMMInfoRequest
+  ? AMMInfoResponse
+  : T extends GatewayBalancesRequest
+  ? GatewayBalancesResponse
+  : T extends NoRippleCheckRequest
+  ? NoRippleCheckResponse
+  : // NOTE: The order of these LedgerRequest types is important
+  // to get the proper type matching overrides based on parameters set
+  // in the request. For example LedgerRequestExpandedTransactionsBinary
+  // should match LedgerRequestExpandedTransactionsOnly, but not
+  // LedgerRequestExpandedAccountsOnly. This is because the
+  // LedgerRequestExpandedTransactionsBinary type is a superset of
+  // LedgerRequestExpandedTransactionsOnly, but not of the other.
+  // This is why LedgerRequestExpandedTransactionsBinary is listed
+  // first in the type list.
+  //
+  // Here is an example using real data:
+  // LedgerRequestExpandedTransactionsBinary = {
+  //   command: 'ledger',
+  //   ledger_index: 'validated',
+  //   expand: true,
+  //   transactions: true,
+  //   binary: true,
+  // }
+  // LedgerRequestExpandedTransactionsOnly = {
+  //   command: 'ledger',
+  //   ledger_index: 'validated',
+  //   expand: true,
+  //   transactions: true,
+  // }
+  // LedgerRequestExpandedAccountsOnly = {
+  //   command: 'ledger',
+  //   ledger_index: 'validated',
+  //   accounts: true,
+  //   expand: true,
+  // }
+  // LedgerRequest = {
+  //   command: 'ledger',
+  //   ledger_index: 'validated',
+  // }
+  //
+  // The type with the most parameters set should be listed first. In this
+  // case LedgerRequestExpandedTransactionsBinary has the most parameters (`expand`, `transactions`, and `binary`)
+  // set, so it is listed first. When TypeScript tries to match the type of
+  // a request to a response, it will try to match the request type to the
+  // response type in the order they are listed. So, if we have a request
+  // with the following parameters:
+  // {
+  //   command: 'ledger',
+  //   ledger_index: 'validated',
+  //   expand: true,
+  //   transactions: true,
+  //   binary: true,
+  // }
+  // TypeScript will first try to match the request type to
+  // LedgerRequestExpandedTransactionsBinary, which will succeed. It will
+  // then try to match the response type to LedgerResponseExpanded, which
+  // will also succeed. If we had listed LedgerRequestExpandedTransactionsOnly
+  // first, TypeScript would have tried to match the request type to
+  // LedgerRequestExpandedTransactionsOnly, which would have succeeded, but
+  // then we'd get the wrong response type, LedgerResponse, instead of
+  // LedgerResponseExpanded.
+  T extends LedgerRequestExpandedTransactionsBinary
+  ? LedgerResponse
+  : T extends LedgerRequestExpandedAccountsAndTransactions
+  ? LedgerResponseExpanded
+  : T extends LedgerRequestExpandedTransactionsOnly
+  ? LedgerResponseExpanded
+  : T extends LedgerRequestExpandedAccountsOnly
+  ? LedgerResponseExpanded
+  : T extends LedgerRequest
+  ? LedgerResponse
+  : T extends LedgerClosedRequest
+  ? LedgerClosedResponse
+  : T extends LedgerCurrentRequest
+  ? LedgerCurrentResponse
+  : T extends LedgerDataRequest
+  ? LedgerDataResponse
+  : T extends LedgerEntryRequest
+  ? LedgerEntryResponse
+  : T extends SubmitRequest
+  ? SubmitResponse
+  : T extends SubmitMultisignedRequest
+  ? SubmitMultisignedResponse
+  : T extends TransactionEntryRequest
+  ? TransactionEntryResponse
+  : T extends TxRequest
+  ? TxResponse
+  : T extends BookOffersRequest
+  ? BookOffersResponse
+  : T extends DepositAuthorizedRequest
+  ? DepositAuthorizedResponse
+  : T extends PathFindRequest
+  ? PathFindResponse
+  : T extends RipplePathFindRequest
+  ? RipplePathFindResponse
+  : T extends ChannelVerifyRequest
+  ? ChannelVerifyResponse
+  : T extends SubscribeRequest
+  ? SubscribeResponse
+  : T extends UnsubscribeRequest
+  ? UnsubscribeResponse
+  : T extends FeeRequest
+  ? FeeResponse
+  : T extends ManifestRequest
+  ? ManifestResponse
+  : T extends ServerInfoRequest
+  ? ServerInfoResponse
+  : T extends ServerStateRequest
+  ? ServerStateResponse
+  : T extends PingRequest
+  ? PingResponse
+  : T extends RandomRequest
+  ? RandomResponse
+  : T extends NFTBuyOffersRequest
+  ? NFTBuyOffersResponse
+  : T extends NFTSellOffersRequest
+  ? NFTSellOffersResponse
+  : T extends NFTInfoRequest
+  ? NFTInfoResponse
+  : T extends NFTHistoryRequest
+  ? NFTHistoryResponse
+  : Response
+
+export type MarkerRequest = Request & {
+  limit?: number
+  marker?: unknown
+}
+
+export type MarkerResponse = Response & {
+  result: {
+    marker?: unknown
+  }
+}
+
+export type RequestAllResponseMap<T> = T extends AccountChannelsRequest
+  ? AccountChannelsResponse
+  : T extends AccountLinesRequest
+  ? AccountLinesResponse
+  : T extends AccountObjectsRequest
+  ? AccountObjectsResponse
+  : T extends AccountOffersRequest
+  ? AccountOffersResponse
+  : T extends AccountTxRequest
+  ? AccountTxResponse
+  : T extends LedgerDataRequest
+  ? LedgerDataResponse
+  : T extends AccountTxRequest
+  ? AccountTxResponse
+  : T extends BookOffersRequest
+  ? BookOffersResponse
+  : MarkerResponse
+
 export {
   // Allow users to define their own requests and responses.  This is useful for releasing experimental versions
   BaseRequest,

package/src/models/methods/ledger.ts

@@ -1,4 +1,5 @@
 import { Ledger } from '../ledger'
+import { LedgerEntryFilter } from '../ledger/LedgerEntry'
 import { Transaction, TransactionAndMetadata } from '../transactions'
 import { TransactionMetadata } from '../transactions/metadata'
 
@@ -65,6 +66,116 @@ export interface LedgerRequest extends BaseRequest, LookupByLedgerRequest {
    * array of queued transactions in the results.
    */
   queue?: boolean
+  /**
+   * If included, filter results to include only this type of ledger object.
+   */
+  type?: LedgerEntryFilter
+}
+
+/**
+ * Retrieve information about the public ledger. Expects a response in the form
+ * of a {@link LedgerResponseExpanded}. Will return full JSON-formatted transaction data instead of string hashes.
+ *
+ * @example
+ * ```ts
+ * const ledger: LedgerRequest = {
+ *  "id": 14,
+ *  "command": "ledger",
+ *  "ledger_index": "validated",
+ *  "full": false,
+ *  "accounts": false,
+ *  "transactions": false,
+ *  "expand": true,
+ *  "owner_funds": false
+ * }
+ * ```
+ *
+ * @category Requests
+ */
+export interface LedgerRequestExpandedTransactionsOnly extends LedgerRequest {
+  expand: true
+  transactions: true
+}
+
+/**
+ * Retrieve information about the public ledger. Expects a response in the form
+ * of a {@link LedgerResponseExpanded}. Will return full JSON-formatted `accountState` data instead of string hashes.
+ *
+ * @example
+ * ```ts
+ * const ledger: LedgerRequest = {
+ *  "id": 14,
+ *  "command": "ledger",
+ *  "ledger_index": "validated",
+ *  "full": false,
+ *  "accounts": true,
+ *  "transactions": false,
+ *  "expand": true,
+ *  "owner_funds": false
+ * }
+ * ```
+ *
+ * @category Requests
+ */
+export interface LedgerRequestExpandedAccountsOnly extends LedgerRequest {
+  expand: true
+  accounts: true
+}
+
+/**
+ * Retrieve information about the public ledger. Expects a response in the form
+ * of a {@link LedgerResponseExpanded}. Will return full JSON-formatted `accountState` and `transactions`
+ * data instead of string hashes.
+ *
+ * @example
+ * ```ts
+ * const ledger: LedgerRequest = {
+ *  "id": 14,
+ *  "command": "ledger",
+ *  "ledger_index": "validated",
+ *  "full": false,
+ *  "accounts": true,
+ *  "transactions": true,
+ *  "expand": true,
+ *  "owner_funds": false
+ * }
+ * ```
+ *
+ * @category Requests
+ */
+export interface LedgerRequestExpandedAccountsAndTransactions
+  extends LedgerRequest {
+  expand: true
+  accounts: true
+  transactions: true
+}
+
+/**
+ * Retrieve information about the public ledger. Expects a response in the form
+ * of a {@link LedgerResponse}. Will return binary (hexadecimal string) format
+ * instead of JSON or string hashes for `transactions` data.
+ *
+ * @example
+ * ```ts
+ * const ledger: LedgerRequest = {
+ *  "id": 14,
+ *  "command": "ledger",
+ *  "ledger_index": "validated",
+ *  "full": false,
+ *  "accounts": true,
+ *  "transactions": true,
+ *  "expand": true,
+ *  "owner_funds": false,
+ *  "binary": true
+ * }
+ * ```
+ *
+ * @category Requests
+ */
+export interface LedgerRequestExpandedTransactionsBinary extends LedgerRequest {
+  expand: true
+  transactions: true
+  binary: true
 }
 
 /**
@@ -96,30 +207,53 @@ export interface LedgerBinary
   transactions?: string[]
 }
 
+interface LedgerResponseBase {
+  /** Unique identifying hash of the entire ledger. */
+  ledger_hash: string
+  /** The Ledger Index of this ledger. */
+  ledger_index: number
+  /**
+   * If true, this is a validated ledger version. If omitted or set to false,
+   * this ledger's data is not final.
+   */
+  queue_data?: Array<LedgerQueueData | string>
+  /**
+   * Array of objects describing queued transactions, in the same order as
+   * the queue. If the request specified expand as true, members contain full
+   * representations of the transactions, in either JSON or binary depending
+   * on whether the request specified binary as true.
+   */
+  validated?: boolean
+}
+
+interface LedgerResponseResult extends LedgerResponseBase {
+  /** The complete header data of this {@link Ledger}. */
+  ledger: LedgerBinary
+}
+
 /**
  * Response expected from a {@link LedgerRequest}.
+ * This is the default request response, triggered when `expand` and `binary` are both false.
  *
  * @category Responses
  */
 export interface LedgerResponse extends BaseResponse {
-  result: {
-    /** The complete header data of this {@link Ledger}. */
-    ledger: Ledger | LedgerBinary
-    /** Unique identifying hash of the entire ledger. */
-    ledger_hash: string
-    /** The Ledger Index of this ledger. */
-    ledger_index: number
-    /**
-     * If true, this is a validated ledger version. If omitted or set to false,
-     * this ledger's data is not final.
-     */
-    queue_data?: Array<LedgerQueueData | string>
-    /**
-     * Array of objects describing queued transactions, in the same order as
-     * the queue. If the request specified expand as true, members contain full
-     * representations of the transactions, in either JSON or binary depending
-     * on whether the request specified binary as true.
-     */
-    validated?: boolean
-  }
+  result: LedgerResponseResult
+}
+
+interface LedgerResponseExpandedResult extends LedgerResponseBase {
+  /** The complete header data of this {@link Ledger}. */
+  ledger: Ledger
+}
+
+/**
+ * Response expected from a {@link LedgerRequest} when the request contains `expanded` is true. See {@link LedgerRequestExpanded}.
+ * This response will contain full JSON-formatted data instead of string hashes.
+ * The response will contain either `accounts` or `transactions` or both.
+ * `binary` will be missing altogether.
+ *
+ * @category Responses
+ */
+export interface LedgerResponseExpanded extends BaseResponse {
+  result: LedgerResponseExpandedResult
 }

package/src/models/methods/ledgerData.ts

@@ -1,4 +1,4 @@
-import { LedgerEntry } from '../ledger'
+import { LedgerEntry, LedgerEntryFilter } from '../ledger'
 
 import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
 
@@ -37,6 +37,10 @@ export interface LedgerDataRequest extends BaseRequest, LookupByLedgerRequest {
    * that response left off.
    */
   marker?: unknown
+  /**
+   * If included, filter results to include only this type of ledger object.
+   */
+  type?: LedgerEntryFilter
 }
 
 export type LedgerDataLabeledLedgerEntry = {

package/src/models/methods/ledgerEntry.ts

@@ -184,7 +184,7 @@ export interface LedgerEntryRequest extends BaseRequest, LookupByLedgerRequest {
  *
  * @category Responses
  */
-export interface LedgerEntryResponse extends BaseResponse {
+export interface LedgerEntryResponse<T = LedgerEntry> extends BaseResponse {
   result: {
     /** The unique ID of this ledger object. */
     index: string
@@ -194,7 +194,7 @@ export interface LedgerEntryResponse extends BaseResponse {
      * Object containing the data of this ledger object, according to the
      * ledger format.
      */
-    node?: LedgerEntry
+    node?: T
     /** The binary representation of the ledger object, as hexadecimal. */
     node_binary?: string
     validated?: boolean

package/src/models/methods/subscribe.ts

@@ -10,6 +10,7 @@ import { OfferCreate, Transaction } from '../transactions'
 import { TransactionMetadata } from '../transactions/metadata'
 
 import type { BaseRequest, BaseResponse } from './baseMethod'
+import { ManifestRequest } from './manifest'
 
 export interface SubscribeBook {
   /**
@@ -433,3 +434,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,5 +1,6 @@
 import { Transaction, TransactionMetadata } from '../transactions'
 import { BaseTransaction } from '../transactions/common'
+import { PseudoTransaction } from '../transactions/transaction'
 
 import { BaseRequest, BaseResponse } from './baseMethod'
 
@@ -11,6 +12,7 @@ import { BaseRequest, BaseResponse } from './baseMethod'
  */
 export interface TxRequest extends BaseRequest {
   command: 'tx'
+  /** The 256-bit hash of the transaction, as hex. */
   transaction: string
   /**
    * If true, return transaction data and metadata as binary serialized to
@@ -39,8 +41,9 @@ export interface TxRequest extends BaseRequest {
  *
  * @category Responses
  */
-export interface TxResponse<T extends BaseTransaction = Transaction>
-  extends BaseResponse {
+export interface TxResponse<
+  T extends BaseTransaction = Transaction | PseudoTransaction,
+> extends BaseResponse {
   result: {
     /** The SHA-512 hash of the transaction. */
     hash: string
@@ -48,7 +51,7 @@ export interface TxResponse<T extends BaseTransaction = 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
+    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.

package/src/models/transactions/NFTokenAcceptOffer.ts

@@ -6,6 +6,7 @@ import {
   parseAmountValue,
   validateBaseTransaction,
 } from './common'
+import type { TransactionMetadataBase } from './metadata'
 
 /**
  *  The NFTokenOfferAccept transaction is used to accept offers
@@ -64,6 +65,11 @@ export interface NFTokenAcceptOffer extends BaseTransaction {
   NFTokenBrokerFee?: Amount
 }
 
+export interface NFTokenAcceptOfferMetadata extends TransactionMetadataBase {
+  // rippled 1.11.0 or later
+  nftoken_id?: string
+}
+
 function validateNFTokenBrokerFee(tx: Record<string, unknown>): void {
   const value = parseAmountValue(tx.NFTokenBrokerFee)
   if (Number.isNaN(value)) {