xrpl 2.13.0 → 3.0.0-beta.0

package/src/client/partialPayment.ts

@@ -3,13 +3,13 @@ import { decode } from 'ripple-binary-codec'
 
 import type {
   AccountTxResponse,
-  Response,
-  ResponseWarning,
   TransactionEntryResponse,
   TransactionStream,
   TxResponse,
 } from '..'
 import type { Amount } from '../models/common'
+import type { RequestResponseMap } from '../models/methods'
+import { BaseRequest, BaseResponse } from '../models/methods/baseMethod'
 import {
   PaymentFlags,
   PseudoTransaction,
@@ -90,7 +90,10 @@ function accountTxHasPartialPayment(response: AccountTxResponse): boolean {
   return foo
 }
 
-function hasPartialPayment(command: string, response: Response): boolean {
+function hasPartialPayment<R extends BaseRequest, T = RequestResponseMap<R>>(
+  command: string,
+  response: T,
+): boolean {
   /* eslint-disable @typescript-eslint/consistent-type-assertions -- Request type is known at runtime from command */
   switch (command) {
     case 'tx':
@@ -111,12 +114,13 @@ function hasPartialPayment(command: string, response: Response): boolean {
  * @param command - Command from the request, tells us what response to expect.
  * @param response - Response to check for a partial payment.
  */
-export function handlePartialPayment(
-  command: string,
-  response: Response,
-): void {
+export function handlePartialPayment<
+  R extends BaseRequest,
+  T = RequestResponseMap<R>,
+>(command: string, response: T): void {
   if (hasPartialPayment(command, response)) {
-    const warnings: ResponseWarning[] = response.warnings ?? []
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- We are checking dynamically and safely.
+    const warnings = (response as BaseResponse).warnings ?? []
 
     const warning = {
       id: WARN_PARTIAL_PAYMENT_CODE,
@@ -125,6 +129,8 @@ export function handlePartialPayment(
 
     warnings.push(warning)
 
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- We are checking dynamically and safely.
+    // @ts-expect-error -- We are checking dynamically and safely.
     response.warnings = warnings
   }
 }

package/src/errors.ts

@@ -1,6 +1,4 @@
 /* eslint-disable max-classes-per-file -- Errors can be defined in the same file */
-import { inspect } from 'util'
-
 /**
  * Base Error class for xrpl.js. All Errors thrown by xrpl.js should throw
  * XrplErrors.
@@ -38,7 +36,7 @@ class XrplError extends Error {
   public toString(): string {
     let result = `[${this.name}(${this.message}`
     if (this.data) {
-      result += `, ${inspect(this.data)}`
+      result += `, ${JSON.stringify(this.data)}`
     }
     result += ')]'
     return result

package/src/index.ts

@@ -1,6 +1,3 @@
-// Broadcast client is experimental
-export { BroadcastClient } from './client/BroadcastClient'
-
 export { Client, ClientOptions } from './client'
 
 export * from './models'
@@ -11,6 +8,7 @@ export { default as ECDSA } from './ECDSA'
 
 export * from './errors'
 
+export { FundingOptions } from './Wallet/fundWallet'
 export { Wallet } from './Wallet'
 
 export { walletFromSecretNumbers } from './Wallet/walletFromSecretNumbers'

package/src/models/ledger/Ledger.ts

@@ -15,7 +15,7 @@ import { LedgerEntry } from './LedgerEntry'
 export default interface Ledger {
   /** The SHA-512Half of this ledger's state tree information. */
   account_hash: string
-  /** All the state information in this ledger. */
+  /** All the state information in this ledger. Admin only. */
   accountState?: LedgerEntry[]
   /** A bit-map of flags relating to the closing of this ledger. */
   close_flags: number

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

@@ -72,6 +72,112 @@ export interface LedgerRequest extends BaseRequest, LookupByLedgerRequest {
   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
+}
+
 /**
  * Special case transaction definition when the request contains `owner_funds: true`.
  */
@@ -101,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/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

@@ -12,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
@@ -50,7 +51,7 @@ export interface TxResponse<
     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)) {

package/src/models/transactions/NFTokenCancelOffer.ts

@@ -1,6 +1,7 @@
 import { ValidationError } from '../../errors'
 
 import { BaseTransaction, validateBaseTransaction } from './common'
+import type { TransactionMetadataBase } from './metadata'
 
 /**
  * The NFTokenCancelOffer transaction deletes existing NFTokenOffer objects.
@@ -26,6 +27,11 @@ export interface NFTokenCancelOffer extends BaseTransaction {
   NFTokenOffers: string[]
 }
 
+export interface NFTokenCancelOfferMetadata extends TransactionMetadataBase {
+  // rippled 1.11.0  or  later
+  nftoken_ids?: string[]
+}
+
 /**
  * Verify the form and type of an NFTokenCancelOffer at runtime.
  *

package/src/models/transactions/NFTokenCreateOffer.ts

@@ -12,6 +12,7 @@ import {
   validateOptionalField,
   Account,
 } from './common'
+import type { TransactionMetadataBase } from './metadata'
 
 /**
  * Transaction Flags for an NFTokenCreateOffer Transaction.
@@ -86,6 +87,11 @@ export interface NFTokenCreateOffer extends BaseTransaction {
   Flags?: number | NFTokenCreateOfferFlagsInterface
 }
 
+export interface NFTokenCreateOfferMetadata extends TransactionMetadataBase {
+  // rippled 1.11.0 or later
+  offer_id?: string
+}
+
 function validateNFTokenSellOfferCases(tx: Record<string, unknown>): void {
   if (tx.Owner != null) {
     throw new ValidationError(

package/src/models/transactions/NFTokenMint.ts

@@ -9,6 +9,7 @@ import {
   validateBaseTransaction,
   validateOptionalField,
 } from './common'
+import type { TransactionMetadataBase } from './metadata'
 
 /**
  * Transaction Flags for an NFTokenMint Transaction.
@@ -101,6 +102,11 @@ export interface NFTokenMint extends BaseTransaction {
   Flags?: number | NFTokenMintFlagsInterface
 }
 
+export interface NFTokenMintMetadata extends TransactionMetadataBase {
+  // rippled 1.11.0 or later
+  nftoken_id?: string
+}
+
 /**
  * Verify the form and type of an NFTokenMint at runtime.
  *

package/src/models/transactions/metadata.ts

@@ -1,5 +1,22 @@
 import { Amount } from '../common'
 
+import { BaseTransaction } from './common'
+import {
+  NFTokenAcceptOffer,
+  NFTokenAcceptOfferMetadata,
+} from './NFTokenAcceptOffer'
+import {
+  NFTokenCancelOffer,
+  NFTokenCancelOfferMetadata,
+} from './NFTokenCancelOffer'
+import {
+  NFTokenCreateOffer,
+  NFTokenCreateOfferMetadata,
+} from './NFTokenCreateOffer'
+import { NFTokenMint, NFTokenMintMetadata } from './NFTokenMint'
+import { Payment, PaymentMetadata } from './payment'
+import type { Transaction } from './transaction'
+
 export interface CreatedNode {
   CreatedNode: {
     LedgerEntryType: string
@@ -59,7 +76,7 @@ export function isDeletedNode(node: Node): node is DeletedNode {
   return Object.prototype.hasOwnProperty.call(node, `DeletedNode`)
 }
 
-export interface TransactionMetadata {
+export interface TransactionMetadataBase {
   AffectedNodes: Node[]
   DeliveredAmount?: Amount
   // "unavailable" possible for transactions before 2014-01-20
@@ -67,3 +84,16 @@ export interface TransactionMetadata {
   TransactionIndex: number
   TransactionResult: string
 }
+
+export type TransactionMetadata<T extends BaseTransaction = Transaction> =
+  T extends Payment
+    ? PaymentMetadata
+    : T extends NFTokenMint
+    ? NFTokenMintMetadata
+    : T extends NFTokenCreateOffer
+    ? NFTokenCreateOfferMetadata
+    : T extends NFTokenAcceptOffer
+    ? NFTokenAcceptOfferMetadata
+    : T extends NFTokenCancelOffer
+    ? NFTokenCancelOfferMetadata
+    : TransactionMetadataBase

package/src/models/transactions/payment.ts

@@ -13,6 +13,7 @@ import {
   isNumber,
   Account,
 } from './common'
+import type { TransactionMetadataBase } from './metadata'
 
 /**
  * Enum representing values for Payment Transaction Flags.
@@ -151,6 +152,11 @@ export interface Payment extends BaseTransaction {
   Flags?: number | PaymentFlagsInterface
 }
 
+export interface PaymentMetadata extends TransactionMetadataBase {
+  DeliveredAmount?: Amount
+  delivered_amount?: Amount | 'unavailable'
+}
+
 /**
  * Verify the form and type of a Payment at runtime.
  *