xrpl 2.14.0 → 3.0.0-beta.1

package/src/client/index.ts

@@ -1,118 +1,81 @@
 /* eslint-disable jsdoc/require-jsdoc -- Request has many aliases, but they don't need unique docs */
-/* eslint-disable @typescript-eslint/member-ordering -- TODO: remove when instance methods aren't members */
+
 /* eslint-disable max-lines -- Client is a large file w/ lots of imports/exports */
-import * as assert from 'assert'
-import { EventEmitter } from 'events'
+import { EventEmitter } from 'eventemitter3'
 
-import { NotFoundError, ValidationError, XrplError } from '../errors'
+import {
+  RippledError,
+  NotFoundError,
+  ValidationError,
+  XrplError,
+} from '../errors'
+import type { LedgerIndex, Balance } from '../models/common'
 import {
   Request,
-  Response,
   // account methods
   AccountChannelsRequest,
   AccountChannelsResponse,
-  AccountCurrenciesRequest,
-  AccountCurrenciesResponse,
   AccountInfoRequest,
-  AccountInfoResponse,
   AccountLinesRequest,
   AccountLinesResponse,
-  AccountNFTsRequest,
-  AccountNFTsResponse,
   AccountObjectsRequest,
   AccountObjectsResponse,
   AccountOffersRequest,
   AccountOffersResponse,
   AccountTxRequest,
   AccountTxResponse,
-  GatewayBalancesRequest,
-  GatewayBalancesResponse,
-  NoRippleCheckRequest,
-  NoRippleCheckResponse,
   // ledger methods
-  LedgerRequest,
-  LedgerResponse,
-  LedgerClosedRequest,
-  LedgerClosedResponse,
-  LedgerCurrentRequest,
-  LedgerCurrentResponse,
   LedgerDataRequest,
   LedgerDataResponse,
-  LedgerEntryRequest,
-  LedgerEntryResponse,
-  // transaction methods
-  SubmitRequest,
-  SubmitResponse,
-  SubmitMultisignedRequest,
-  SubmitMultisignedResponse,
-  TransactionEntryRequest,
-  TransactionEntryResponse,
-  TxRequest,
   TxResponse,
-  // path and order book methods
-  BookOffersRequest,
-  BookOffersResponse,
-  DepositAuthorizedRequest,
-  DepositAuthorizedResponse,
-  PathFindRequest,
-  PathFindResponse,
-  RipplePathFindRequest,
-  RipplePathFindResponse,
-  // payment channel methods
-  ChannelVerifyRequest,
-  ChannelVerifyResponse,
-  // server info methods
-  FeeRequest,
-  FeeResponse,
-  ManifestRequest,
-  ManifestResponse,
-  ServerInfoRequest,
-  ServerInfoResponse,
-  ServerStateRequest,
-  ServerStateResponse,
-  // utility methods
-  PingRequest,
-  PingResponse,
-  RandomRequest,
-  RandomResponse,
-  LedgerStream,
-  ValidationStream,
-  TransactionStream,
-  PathFindStream,
-  PeerStatusStream,
-  ConsensusStream,
-  SubscribeRequest,
-  SubscribeResponse,
-  UnsubscribeRequest,
-  UnsubscribeResponse,
-  // NFT methods
-  NFTBuyOffersRequest,
-  NFTBuyOffersResponse,
-  NFTSellOffersRequest,
-  NFTSellOffersResponse,
-  // clio only methods
-  NFTInfoRequest,
-  NFTInfoResponse,
-  NFTHistoryRequest,
-  NFTHistoryResponse,
-  // AMM methods
-  AMMInfoRequest,
-  AMMInfoResponse,
-  ServerDefinitionsRequest,
-  ServerDefinitionsResponse,
 } from '../models/methods'
-import { BaseRequest, BaseResponse } from '../models/methods/baseMethod'
+import type {
+  RequestResponseMap,
+  RequestAllResponseMap,
+  MarkerRequest,
+  MarkerResponse,
+  SubmitResponse,
+} from '../models/methods'
+import type { BookOffer, BookOfferCurrency } from '../models/methods/bookOffers'
+import type {
+  EventTypes,
+  OnEventToListenerMap,
+} from '../models/methods/subscribe'
+import type { SubmittableTransaction } from '../models/transactions'
+import { setTransactionFlagsToNumber } from '../models/utils/flags'
 import {
-  autofill,
   ensureClassicAddress,
-  getLedgerIndex,
-  getOrderbook,
-  getBalances,
-  getXrpBalance,
-  submit,
-  submitAndWait,
+  submitRequest,
+  getSignedTx,
+  getLastLedgerSequence,
+  waitForFinalTransactionOutcome,
 } from '../sugar'
-import fundWallet from '../Wallet/fundWallet'
+import {
+  setValidAddresses,
+  setNextValidSequenceNumber,
+  calculateFeePerTransactionType,
+  setLatestValidatedLedgerSequence,
+  checkAccountDeleteBlockers,
+  txNeedsNetworkID,
+} from '../sugar/autofill'
+import { formatBalances } from '../sugar/balances'
+import {
+  validateOrderbookOptions,
+  createBookOffersRequest,
+  requestAllOffers,
+  reverseRequest,
+  extractOffers,
+  combineOrders,
+  separateBuySellOrders,
+  sortAndLimitOffers,
+} from '../sugar/getOrderbook'
+import { dropsToXrp, hashes, isValidClassicAddress } from '../utils'
+import { Wallet } from '../Wallet'
+import {
+  type FaucetRequestBody,
+  FundingOptions,
+  requestFunding,
+} from '../Wallet/fundWallet'
 
 import {
   Connection,
@@ -127,10 +90,32 @@ import {
 export interface ClientOptions extends ConnectionUserOptions {
   feeCushion?: number
   maxFeeXRP?: string
-  proxy?: string
   timeout?: number
 }
 
+// Make sure to update both this and `RequestNextPageReturnMap` at the same time
+type RequestNextPageType =
+  | AccountChannelsRequest
+  | AccountLinesRequest
+  | AccountObjectsRequest
+  | AccountOffersRequest
+  | AccountTxRequest
+  | LedgerDataRequest
+
+type RequestNextPageReturnMap<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
+  : never
+
 /**
  * Get the response key / property name that contains the listed data for a
  * command. This varies from command to command, but we need to know it to
@@ -160,19 +145,10 @@ function getCollectKeyFromCommand(command: string): string | null {
 }
 
 function clamp(value: number, min: number, max: number): number {
-  assert.ok(min <= max, 'Illegal clamp bounds')
-  return Math.min(Math.max(value, min), max)
-}
-
-interface MarkerRequest extends BaseRequest {
-  limit?: number
-  marker?: unknown
-}
-
-interface MarkerResponse extends BaseResponse {
-  result: {
-    marker?: unknown
+  if (min > max) {
+    throw new Error('Illegal clamp bounds')
   }
+  return Math.min(Math.max(value, min), max)
 }
 
 const DEFAULT_FEE_CUSHION = 1.2
@@ -188,7 +164,7 @@ const NORMAL_DISCONNECT_CODE = 1000
  *
  * @category Clients
  */
-class Client extends EventEmitter {
+class Client extends EventEmitter<EventTypes> {
   /*
    * Underlying connection to rippled.
    */
@@ -228,6 +204,12 @@ class Client extends EventEmitter {
    * @param server - URL of the server to connect to.
    * @param options - Options for client settings.
    * @category Constructor
+   *
+   * @example
+   * ```ts
+   * import { Client } from "xrpl"
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * ```
    */
   // eslint-disable-next-line max-lines-per-function -- okay because we have to set up all the connection handlers
   public constructor(server: string, options: ClientOptions = {}) {
@@ -304,87 +286,34 @@ class Client extends EventEmitter {
     return this.connection.getUrl()
   }
 
-  /**
-   * @category Network
-   */
-  public async request(
-    r: AccountChannelsRequest,
-  ): Promise<AccountChannelsResponse>
-  public async request(
-    r: AccountCurrenciesRequest,
-  ): Promise<AccountCurrenciesResponse>
-  public async request(r: AccountInfoRequest): Promise<AccountInfoResponse>
-  public async request(r: AccountLinesRequest): Promise<AccountLinesResponse>
-  public async request(r: AccountNFTsRequest): Promise<AccountNFTsResponse>
-  public async request(
-    r: AccountObjectsRequest,
-  ): Promise<AccountObjectsResponse>
-  public async request(r: AccountOffersRequest): Promise<AccountOffersResponse>
-  public async request(r: AccountTxRequest): Promise<AccountTxResponse>
-  public async request(r: AMMInfoRequest): Promise<AMMInfoResponse>
-  public async request(r: BookOffersRequest): Promise<BookOffersResponse>
-  public async request(r: ChannelVerifyRequest): Promise<ChannelVerifyResponse>
-  public async request(
-    r: DepositAuthorizedRequest,
-  ): Promise<DepositAuthorizedResponse>
-  public async request(r: FeeRequest): Promise<FeeResponse>
-  public async request(
-    r: GatewayBalancesRequest,
-  ): Promise<GatewayBalancesResponse>
-  public async request(r: LedgerRequest): Promise<LedgerResponse>
-  public async request(r: LedgerClosedRequest): Promise<LedgerClosedResponse>
-  public async request(r: LedgerCurrentRequest): Promise<LedgerCurrentResponse>
-  public async request(r: LedgerDataRequest): Promise<LedgerDataResponse>
-  public async request(r: LedgerEntryRequest): Promise<LedgerEntryResponse>
-  public async request(r: ManifestRequest): Promise<ManifestResponse>
-  public async request(r: NFTBuyOffersRequest): Promise<NFTBuyOffersResponse>
-  public async request(r: NFTSellOffersRequest): Promise<NFTSellOffersResponse>
-  public async request(r: NFTInfoRequest): Promise<NFTInfoResponse>
-  public async request(r: NFTHistoryRequest): Promise<NFTHistoryResponse>
-  public async request(r: NoRippleCheckRequest): Promise<NoRippleCheckResponse>
-  public async request(r: PathFindRequest): Promise<PathFindResponse>
-  public async request(r: PingRequest): Promise<PingResponse>
-  public async request(r: RandomRequest): Promise<RandomResponse>
-  public async request(
-    r: RipplePathFindRequest,
-  ): Promise<RipplePathFindResponse>
-  public async request(
-    r: ServerDefinitionsRequest,
-  ): Promise<ServerDefinitionsResponse>
-  public async request(r: ServerInfoRequest): Promise<ServerInfoResponse>
-  public async request(r: ServerStateRequest): Promise<ServerStateResponse>
-  public async request(r: SubmitRequest): Promise<SubmitResponse>
-  public async request(
-    r: SubmitMultisignedRequest,
-  ): Promise<SubmitMultisignedResponse>
-  public request(r: SubscribeRequest): Promise<SubscribeResponse>
-  public request(r: UnsubscribeRequest): Promise<UnsubscribeResponse>
-  public async request(
-    r: TransactionEntryRequest,
-  ): Promise<TransactionEntryResponse>
-  public async request(r: TxRequest): Promise<TxResponse>
-  public async request<R extends BaseRequest, T extends BaseResponse>(
-    r: R,
-  ): Promise<T>
   /**
    * Makes a request to the client with the given command and
    * additional request body parameters.
    *
+   * @category Network
+   *
    * @param req - Request to send to the server.
    * @returns The response from the server.
-   * @category Network
+   *
+   * @example
+   * ```ts
+   * const response = await client.request({
+   *   command: 'account_info',
+   *   account: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
+   * })
+   * console.log(response)
+   * ```
    */
-  public async request<R extends Request, T extends Response>(
+  public async request<R extends Request, T = RequestResponseMap<R>>(
     req: R,
   ): Promise<T> {
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Necessary for overloading
-    const response = (await this.connection.request({
+    const response = await this.connection.request<R, T>({
       ...req,
       account: req.account
         ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Must be string
           ensureClassicAddress(req.account as string)
         : undefined,
-    })) as T
+    })
 
     // mutates `response` to add warnings
     handlePartialPayment(req.command, response)
@@ -392,44 +321,34 @@ class Client extends EventEmitter {
     return response
   }
 
-  /**
-   * @category Network
-   */
-  public async requestNextPage(
-    req: AccountChannelsRequest,
-    resp: AccountChannelsResponse,
-  ): Promise<AccountChannelsResponse>
-  public async requestNextPage(
-    req: AccountLinesRequest,
-    resp: AccountLinesResponse,
-  ): Promise<AccountLinesResponse>
-  public async requestNextPage(
-    req: AccountObjectsRequest,
-    resp: AccountObjectsResponse,
-  ): Promise<AccountObjectsResponse>
-  public async requestNextPage(
-    req: AccountOffersRequest,
-    resp: AccountOffersResponse,
-  ): Promise<AccountOffersResponse>
-  public async requestNextPage(
-    req: AccountTxRequest,
-    resp: AccountTxResponse,
-  ): Promise<AccountTxResponse>
-  public async requestNextPage(
-    req: LedgerDataRequest,
-    resp: LedgerDataResponse,
-  ): Promise<LedgerDataResponse>
   /**
    * Requests the next page of data.
    *
+   * @category Network
+   *
    * @param req - Request to send.
    * @param resp - Response with the marker to use in the request.
    * @returns The response with the next page of data.
+   *
+   * @example
+   * ```ts
+   * const response = await client.request({
+   *  command: 'account_tx',
+   *  account: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
+   * })
+   * console.log(response)
+   * const nextResponse = await client.requestNextPage({
+   *   command: 'account_tx',
+   *   account: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
+   * },
+   * response)
+   * console.log(nextResponse)
+   * ```
    */
   public async requestNextPage<
-    T extends MarkerRequest,
-    U extends MarkerResponse,
-  >(req: T, resp: U): Promise<U> {
+    T extends RequestNextPageType,
+    U extends RequestNextPageReturnMap<T>,
+  >(req: T, resp: U): Promise<RequestNextPageReturnMap<T>> {
     if (!resp.result.marker) {
       return Promise.reject(
         new NotFoundError('response does not have a next page'),
@@ -443,7 +362,13 @@ class Client extends EventEmitter {
   /**
    * Event handler for subscription streams.
    *
-   * @example
+   * @category Network
+   *
+   * @param eventName - Name of the event. Only forwards streams.
+   * @param listener - Function to run on event.
+   * @returns This, because it inherits from EventEmitter.
+   *
+   * * @example
    * ```ts
    * const api = new Client('wss://s.altnet.rippletest.net:51233')
    *
@@ -458,68 +383,15 @@ class Client extends EventEmitter {
    *     streams: ['transactions_proposed']
    * })
    * ```
-   *
-   * @category Network
-   */
-  public on(event: 'connected', listener: () => void): this
-  public on(event: 'disconnected', listener: (code: number) => void): this
-  public on(
-    event: 'ledgerClosed',
-    listener: (ledger: LedgerStream) => void,
-  ): this
-  public on(
-    event: 'validationReceived',
-    listener: (validation: ValidationStream) => void,
-  ): this
-  public on(
-    event: 'transaction',
-    listener: (tx: TransactionStream) => void,
-  ): this
-  public on(
-    event: 'peerStatusChange',
-    listener: (status: PeerStatusStream) => void,
-  ): this
-  public on(
-    event: 'consensusPhase',
-    listener: (phase: ConsensusStream) => void,
-  ): this
-  public on(
-    event: 'manifestReceived',
-    listener: (manifest: ManifestResponse) => void,
-  ): this
-  public on(event: 'path_find', listener: (path: PathFindStream) => void): this
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- needs to be any for overload
-  public on(event: 'error', listener: (...err: any[]) => void): this
-  /**
-   * Event handler for subscription streams.
-   *
-   * @param eventName - Name of the event. Only forwards streams.
-   * @param listener - Function to run on event.
-   * @returns This, because it inherits from EventEmitter.
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- needs to be any for overload
-  public on(eventName: string, listener: (...args: any[]) => void): this {
+  public on<
+    T extends EventTypes,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- needs to be any for overload
+    U extends (...args: any[]) => void = OnEventToListenerMap<T>,
+  >(eventName: T, listener: U): this {
     return super.on(eventName, listener)
   }
 
-  /**
-   * @category Network
-   */
-  public async requestAll(
-    req: AccountChannelsRequest,
-  ): Promise<AccountChannelsResponse[]>
-  public async requestAll(
-    req: AccountLinesRequest,
-  ): Promise<AccountLinesResponse[]>
-  public async requestAll(
-    req: AccountObjectsRequest,
-  ): Promise<AccountObjectsResponse[]>
-  public async requestAll(
-    req: AccountOffersRequest,
-  ): Promise<AccountOffersResponse[]>
-  public async requestAll(req: AccountTxRequest): Promise<AccountTxResponse[]>
-  public async requestAll(req: BookOffersRequest): Promise<BookOffersResponse[]>
-  public async requestAll(req: LedgerDataRequest): Promise<LedgerDataResponse[]>
   /**
    * Makes multiple paged requests to the client to return a given number of
    * resources. Multiple paged requests will be made until the `limit`
@@ -533,15 +405,27 @@ class Client extends EventEmitter {
    * general use. Instead, use rippled's built-in pagination and make multiple
    * requests as needed.
    *
+   * @category Network
+   *
    * @param request - The initial request to send to the server.
    * @param collect - (Optional) the param to use to collect the array of resources (only needed if command is unknown).
    * @returns The array of all responses.
    * @throws ValidationError if there is no collection key (either from a known command or for the unknown command).
+   *
+   * @example
+   * // Request all ledger data pages
+   * const allResponses = await client.requestAll({ command: 'ledger_data' });
+   * console.log(allResponses);
+   *
+   * @example
+   * // Request all transaction data pages
+   * const allResponses = await client.requestAll({ command: 'transaction_data' });
+   * console.log(allResponses);
    */
-  public async requestAll<T extends MarkerRequest, U extends MarkerResponse>(
-    request: T,
-    collect?: string,
-  ): Promise<U[]> {
+  public async requestAll<
+    T extends MarkerRequest,
+    U = RequestAllResponseMap<T>,
+  >(request: T, collect?: string): Promise<U[]> {
     /*
      * The data under collection is keyed based on the command. Fail if command
      * not recognized and collection key not provided.
@@ -569,7 +453,7 @@ class Client extends EventEmitter {
       // eslint-disable-next-line no-await-in-loop -- Necessary for this, it really has to wait
       const singleResponse = await this.connection.request(repeatProps)
       // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Should be true
-      const singleResult = (singleResponse as U).result
+      const singleResult = (singleResponse as MarkerResponse).result
       if (!(collectKey in singleResult)) {
         throw new XrplError(`${collectKey} not in result`)
       }
@@ -591,6 +475,16 @@ class Client extends EventEmitter {
 
   /**
    * Get networkID and buildVersion from server_info
+   *
+   * @returns void
+   * @example
+   * ```ts
+   * const { Client } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * await client.getServerInfo()
+   * console.log(client.networkID)
+   * console.log(client.buildVersion)
+   * ```
    */
   public async getServerInfo(): Promise<void> {
     try {
@@ -623,6 +517,15 @@ class Client extends EventEmitter {
    * before exiting your application.
    * @returns A promise that resolves with a void value when a connection is established.
    * @category Network
+   *
+   * @example
+   * ```ts
+   * const { Client } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * await client.connect()
+   * // do something with the client
+   * await client.disconnect()
+   * ```
    */
   public async connect(): Promise<void> {
     return this.connection.connect().then(async () => {
@@ -664,54 +567,583 @@ class Client extends EventEmitter {
    *
    * @returns Whether the client instance is connected.
    * @category Network
+   * @example
+   * ```ts
+   * const { Client } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * await client.connect()
+   * console.log(client.isConnected())
+   * // true
+   * await client.disconnect()
+   * console.log(client.isConnected())
+   * // false
+   * ```
    */
   public isConnected(): boolean {
     return this.connection.isConnected()
   }
 
   /**
+   * Autofills fields in a transaction. This will set `Sequence`, `Fee`,
+   * `lastLedgerSequence` according to the current state of the server this Client
+   * is connected to. It also converts all X-Addresses to classic addresses and
+   * flags interfaces into numbers.
+   *
    * @category Core
+   *
+   * @example
+   *
+   * ```ts
+   * const { Client } = require('xrpl')
+   *
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   *
+   * async function createAndAutofillTransaction() {
+   *   const transaction = {
+   *     TransactionType: 'Payment',
+   *     Account: 'rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh',
+   *     Destination: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
+   *     Amount: '10000000' // 10 XRP in drops (1/1,000,000th of an XRP)
+   *   }
+   *
+   *   try {
+   *     const autofilledTransaction = await client.autofill(transaction)
+   *     console.log(autofilledTransaction)
+   *   } catch (error) {
+   *     console.error(`Failed to autofill transaction: ${error}`)
+   *   }
+   * }
+   *
+   * createAndAutofillTransaction()
+   * ```
+   *
+   * Autofill helps fill in fields which should be included in a transaction, but can be determined automatically
+   * such as `LastLedgerSequence` and `Fee`. If you override one of the fields `autofill` changes, your explicit
+   * values will be used instead. By default, this is done as part of `submit` and `submitAndWait` when you pass
+   * in an unsigned transaction along with your wallet to be submitted.
+   *
+   * @template T
+   * @param transaction - A {@link SubmittableTransaction} in JSON format
+   * @param signersCount - The expected number of signers for this transaction.
+   * Only used for multisigned transactions.
+   * @returns The autofilled transaction.
    */
-  public autofill = autofill
+  public async autofill<T extends SubmittableTransaction>(
+    transaction: T,
+    signersCount?: number,
+  ): Promise<T> {
+    const tx = { ...transaction }
+
+    setValidAddresses(tx)
+
+    setTransactionFlagsToNumber(tx)
+
+    const promises: Array<Promise<void>> = []
+    if (tx.NetworkID == null) {
+      tx.NetworkID = txNeedsNetworkID(this) ? this.networkID : undefined
+    }
+    if (tx.Sequence == null) {
+      promises.push(setNextValidSequenceNumber(this, tx))
+    }
+    if (tx.Fee == null) {
+      promises.push(calculateFeePerTransactionType(this, tx, signersCount))
+    }
+    if (tx.LastLedgerSequence == null) {
+      promises.push(setLatestValidatedLedgerSequence(this, tx))
+    }
+    if (tx.TransactionType === 'AccountDelete') {
+      promises.push(checkAccountDeleteBlockers(this, tx))
+    }
+
+    return Promise.all(promises).then(() => tx)
+  }
 
   /**
+   * Submits a signed/unsigned transaction.
+   * Steps performed on a transaction:
+   *    1. Autofill.
+   *    2. Sign & Encode.
+   *    3. Submit.
+   *
    * @category Core
+   *
+   * @param transaction - A transaction to autofill, sign & encode, and submit.
+   * @param opts - (Optional) Options used to sign and submit a transaction.
+   * @param opts.autofill - If true, autofill a transaction.
+   * @param opts.failHard - If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
+   * @param opts.wallet - A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
+   *
+   * @returns A promise that contains SubmitResponse.
+   * @throws RippledError if submit request fails.
+   *
+   * @example
+   * ```ts
+   * const { Client, Wallet } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * await client.connect()
+   * const wallet = Wallet.generate()
+   * const transaction = {
+   *   TransactionType: 'Payment',
+   *   Account: wallet.classicAddress,
+   *   Destination: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
+   *   Amount: '10000000' // 10 XRP in drops (1/1,000,000th of an XRP)
+   * }
+   * const submitResponse = await client.submit(transaction, { wallet })
+   * console.log(submitResponse)
+   * ```
    */
-  public submit = submit
+  public async submit(
+    transaction: SubmittableTransaction | string,
+    opts?: {
+      // If true, autofill a transaction.
+      autofill?: boolean
+      // If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
+      failHard?: boolean
+      // A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
+      wallet?: Wallet
+    },
+  ): Promise<SubmitResponse> {
+    const signedTx = await getSignedTx(this, transaction, opts)
+    return submitRequest(this, signedTx, opts?.failHard)
+  }
+
   /**
+   * Asynchronously submits a transaction and verifies that it has been included in a
+   * validated ledger (or has errored/will not be included for some reason).
+   * See [Reliable Transaction Submission](https://xrpl.org/reliable-transaction-submission.html).
+   *
    * @category Core
+   *
+   * @example
+   *
+   * ```ts
+   * const { Client, Wallet } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   *
+   * async function submitTransaction() {
+   *   const senderWallet = client.fundWallet()
+   *   const recipientWallet = client.fundWallet()
+   *
+   *   const transaction = {
+   *     TransactionType: 'Payment',
+   *     Account: senderWallet.address,
+   *     Destination: recipientWallet.address,
+   *     Amount: '10'
+   *   }
+   *
+   *   try {
+   *     await client.submit(signedTransaction, { wallet: senderWallet })
+   *     console.log(result)
+   *   } catch (error) {
+   *     console.error(`Failed to submit transaction: ${error}`)
+   *   }
+   * }
+   *
+   * submitTransaction()
+   * ```
+   *
+   * In this example we submit a payment transaction between two newly created testnet accounts.
+   *
+   * Under the hood, `submit` will call `client.autofill` by default, and because we've passed in a `Wallet` it
+   * Will also sign the transaction for us before submitting the signed transaction binary blob to the ledger.
+   *
+   * This is similar to `submitAndWait` which does all of the above, but also waits to see if the transaction has been validated.
+   * @param transaction - A transaction to autofill, sign & encode, and submit.
+   * @param opts - (Optional) Options used to sign and submit a transaction.
+   * @param opts.autofill - If true, autofill a transaction.
+   * @param opts.failHard - If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
+   * @param opts.wallet - A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
+   * @throws Connection errors: If the `Client` object is unable to establish a connection to the specified WebSocket endpoint,
+   * an error will be thrown.
+   * @throws Transaction errors: If the submitted transaction is invalid or cannot be included in a validated ledger for any
+   * reason, the promise returned by `submitAndWait()` will be rejected with an error. This could include issues with insufficient
+   * balance, invalid transaction fields, or other issues specific to the transaction being submitted.
+   * @throws Ledger errors: If the ledger being used to submit the transaction is undergoing maintenance or otherwise unavailable,
+   * an error will be thrown.
+   * @throws Timeout errors: If the transaction takes longer than the specified timeout period to be included in a validated
+   * ledger, the promise returned by `submitAndWait()` will be rejected with an error.
+   * @returns A promise that contains TxResponse, that will return when the transaction has been validated.
    */
-  public submitAndWait = submitAndWait
+  public async submitAndWait<
+    T extends SubmittableTransaction = SubmittableTransaction,
+  >(
+    transaction: T | string,
+    opts?: {
+      // If true, autofill a transaction.
+      autofill?: boolean
+      // If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
+      failHard?: boolean
+      // A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
+      wallet?: Wallet
+    },
+  ): Promise<TxResponse<T>> {
+    const signedTx = await getSignedTx(this, transaction, opts)
+
+    const lastLedger = getLastLedgerSequence(signedTx)
+    if (lastLedger == null) {
+      throw new ValidationError(
+        'Transaction must contain a LastLedgerSequence value for reliable submission.',
+      )
+    }
+
+    const response = await submitRequest(this, signedTx, opts?.failHard)
+
+    const txHash = hashes.hashSignedTx(signedTx)
+    return waitForFinalTransactionOutcome(
+      this,
+      txHash,
+      lastLedger,
+      response.result.engine_result,
+    )
+  }
 
   /**
+   * Deprecated: Use autofill instead, provided for users familiar with v1
+   *
+   * @param transaction - A {@link Transaction} in JSON format
+   * @param signersCount - The expected number of signers for this transaction.
+   * Only used for multisigned transactions.
    * @deprecated Use autofill instead, provided for users familiar with v1
    */
-  public prepareTransaction = autofill
+  public async prepareTransaction(
+    transaction: SubmittableTransaction,
+    signersCount?: number,
+  ): ReturnType<Client['autofill']> {
+    return this.autofill(transaction, signersCount)
+  }
 
   /**
+   * Retrieves the XRP balance of a given account address.
+   *
    * @category Abstraction
+   *
+   * @example
+   * ```ts
+   * const client = new Client(wss://s.altnet.rippletest.net:51233)
+   * await client.connect()
+   * const balance = await client.getXrpBalance('rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn')
+   * console.log(balance)
+   * await client.disconnect()
+   * /// '200'
+   * ```
+   *
+   * @param address - The XRP address to retrieve the balance for.
+   * @param [options] - Additional options for fetching the balance (optional).
+   * @param [options.ledger_hash] - The hash of the ledger to retrieve the balance from (optional).
+   * @param [options.ledger_index] - The index of the ledger to retrieve the balance from (optional).
+   * @returns A promise that resolves with the XRP balance as a number.
    */
-  public getXrpBalance = getXrpBalance
+  public async getXrpBalance(
+    address: string,
+    options: {
+      ledger_hash?: string
+      ledger_index?: LedgerIndex
+    } = {},
+  ): Promise<number> {
+    const xrpRequest: AccountInfoRequest = {
+      command: 'account_info',
+      account: address,
+      ledger_index: options.ledger_index ?? 'validated',
+      ledger_hash: options.ledger_hash,
+    }
+    const response = await this.request(xrpRequest)
+    return dropsToXrp(response.result.account_data.Balance)
+  }
 
   /**
+   * Get XRP/non-XRP balances for an account.
+   *
    * @category Abstraction
+   *
+   * @example
+   * ```ts
+   * const { Client } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * await client.connect()
+   *
+   * async function getAccountBalances(address) {
+   *   try {
+   *     const options = {
+   *       ledger_index: 'validated',
+   *       limit: 10
+   *     };
+   *
+   *     const balances = await xrplClient.getBalances(address, options);
+   *
+   *     console.log('Account Balances:');
+   *     balances.forEach((balance) => {
+   *       console.log(`Currency: ${balance.currency}`);
+   *       console.log(`Value: ${balance.value}`);
+   *       console.log(`Issuer: ${balance.issuer}`);
+   *       console.log('---');
+   *     });
+   *   } catch (error) {
+   *     console.error('Error retrieving account balances:', error);
+   *   }
+   * }
+   *
+   * const address = 'rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh';
+   * await getAccountBalances(address);
+   * await client.disconnect();
+   * ```
+   *
+   * @param address - Address of the account to retrieve balances for.
+   * @param options - Allows the client to specify a ledger_hash, ledger_index,
+   * filter by peer, and/or limit number of balances.
+   * @param options.ledger_index - Retrieve the account balances at a given
+   * ledger_index.
+   * @param options.ledger_hash - Retrieve the account balances at the ledger with
+   * a given ledger_hash.
+   * @param options.peer - Filter balances by peer.
+   * @param options.limit - Limit number of balances to return.
+   * @returns An array of XRP/non-XRP balances for the given account.
    */
-  public getBalances = getBalances
+  // eslint-disable-next-line max-lines-per-function -- Longer definition is required for end users to see the definition.
+  public async getBalances(
+    address: string,
+    options: {
+      ledger_hash?: string
+      ledger_index?: LedgerIndex
+      peer?: string
+      limit?: number
+    } = {},
+  ): Promise<
+    Array<{ value: string; currency: string; issuer?: string | undefined }>
+  > {
+    const balances: Balance[] = []
+
+    // get XRP balance
+    let xrpPromise: Promise<number> = Promise.resolve(0)
+    if (!options.peer) {
+      xrpPromise = this.getXrpBalance(address, {
+        ledger_hash: options.ledger_hash,
+        ledger_index: options.ledger_index,
+      })
+    }
+
+    // get non-XRP balances
+    const linesRequest: AccountLinesRequest = {
+      command: 'account_lines',
+      account: address,
+      ledger_index: options.ledger_index ?? 'validated',
+      ledger_hash: options.ledger_hash,
+      peer: options.peer,
+      limit: options.limit,
+    }
+    const linesPromise = this.requestAll(linesRequest)
+
+    // combine results
+    await Promise.all([xrpPromise, linesPromise]).then(
+      ([xrpBalance, linesResponses]) => {
+        const accountLinesBalance = linesResponses.flatMap((response) =>
+          formatBalances(response.result.lines),
+        )
+        if (xrpBalance !== 0) {
+          balances.push({ currency: 'XRP', value: xrpBalance.toString() })
+        }
+        balances.push(...accountLinesBalance)
+      },
+    )
+    return balances.slice(0, options.limit)
+  }
 
   /**
+   * Fetch orderbook (buy/sell orders) between two currency pairs. This checks both sides of the orderbook
+   * by making two `order_book` requests (with the second reversing takerPays and takerGets). Returned offers are
+   * not normalized in this function, so either currency could be takerGets or takerPays.
+   *
    * @category Abstraction
+   *
+   * @param currency1 - Specification of one currency involved. (With a currency code and optionally an issuer)
+   * @param currency2 - Specification of a second currency involved. (With a currency code and optionally an issuer)
+   * @param options - Options allowing the client to specify ledger_index,
+   * ledger_hash, filter by taker, and/or limit number of orders.
+   * @param options.ledger_index - Retrieve the orderbook at a given ledger_index.
+   * @param options.ledger_hash - Retrieve the orderbook at the ledger with a
+   * given ledger_hash.
+   * @param options.taker - Filter orders by taker.
+   * @param options.limit - The limit passed into each book_offers request.
+   * Can return more than this due to two calls being made. Defaults to 20.
+   * @returns An object containing buy and sell objects.
    */
-  public getOrderbook = getOrderbook
+
+  public async getOrderbook(
+    currency1: BookOfferCurrency,
+    currency2: BookOfferCurrency,
+    options: {
+      limit?: number
+      ledger_index?: LedgerIndex
+      ledger_hash?: string | null
+      taker?: string | null
+    } = {},
+  ): Promise<{
+    buy: BookOffer[]
+    sell: BookOffer[]
+  }> {
+    validateOrderbookOptions(options)
+
+    const request = createBookOffersRequest(currency1, currency2, options)
+
+    const directOfferResults = await requestAllOffers(this, request)
+    const reverseOfferResults = await requestAllOffers(
+      this,
+      reverseRequest(request),
+    )
+
+    const directOffers = extractOffers(directOfferResults)
+    const reverseOffers = extractOffers(reverseOfferResults)
+
+    const orders = combineOrders(directOffers, reverseOffers)
+
+    const { buy, sell } = separateBuySellOrders(orders)
+
+    /*
+     * Sort the orders
+     * for both buys and sells, lowest quality is closest to mid-market
+     * we sort the orders so that earlier orders are closer to mid-market
+     */
+    return {
+      buy: sortAndLimitOffers(buy, options.limit),
+      sell: sortAndLimitOffers(sell, options.limit),
+    }
+  }
 
   /**
+   * Returns the index of the most recently validated ledger.
+   *
    * @category Abstraction
+   *
+   * @returns The most recently validated ledger index.
+   *
+   * @example
+   * ```ts
+   * const { Client } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * await client.connect()
+   * const ledgerIndex = await client.getLedgerIndex()
+   * console.log(ledgerIndex)
+   * // 884039
+   * ```
    */
-  public getLedgerIndex = getLedgerIndex
+  public async getLedgerIndex(): Promise<number> {
+    const ledgerResponse = await this.request({
+      command: 'ledger',
+      ledger_index: 'validated',
+    })
+    return ledgerResponse.result.ledger_index
+  }
 
   /**
+   * The fundWallet() method is used to send an amount of XRP (usually 1000) to a new (randomly generated)
+   * or existing XRP Ledger wallet.
+   *
    * @category Faucet
+   *
+   * @example
+   *
+   * Example 1: Fund a randomly generated wallet
+   * const { Client, Wallet } = require('xrpl')
+   *
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * await client.connect()
+   * const { balance, wallet } = await client.fundWallet()
+   *
+   * Under the hood, this will use `Wallet.generate()` to create a new random wallet, then ask a testnet faucet
+   * To send it XRP on ledger to make it a real account. If successful, this will return the new account balance in XRP
+   * Along with the Wallet object to track the keys for that account. If you'd like, you can also re-fill an existing
+   * Account by passing in a Wallet you already have.
+   * ```ts
+   * const api = new xrpl.Client("wss://s.altnet.rippletest.net:51233")
+   * await api.connect()
+   * const { wallet, balance } = await api.fundWallet()
+   * ```
+   *
+   * Example 2: Fund wallet using a custom faucet host and known wallet address
+   *
+   * `fundWallet` will try to infer the url of a faucet API from the network your client is connected to.
+   * There are hardcoded default faucets for popular test networks like testnet and devnet.
+   * However, if you're working with a newer or more obscure network, you may have to specify the faucetHost
+   * And faucetPath so `fundWallet` can ask that faucet to fund your wallet.
+   *
+   * ```ts
+   * const newWallet = Wallet.generate()
+   * const { balance, wallet  } = await client.fundWallet(newWallet, {
+   *       amount: '10',
+   *       faucetHost: 'https://custom-faucet.example.com',
+   *       faucetPath: '/accounts'
+   *     })
+   *     console.log(`Sent 10 XRP to wallet: ${address} from the given faucet. Resulting balance: ${balance} XRP`)
+   *   } catch (error) {
+   *     console.error(`Failed to fund wallet: ${error}`)
+   *   }
+   * }
+   * ```
+   *
+   * @param wallet - An existing XRPL Wallet to fund. If undefined or null, a new Wallet will be created.
+   * @param options - See below.
+   * @param options.faucetHost - A custom host for a faucet server. On devnet,
+   * testnet, AMM devnet, and HooksV3 testnet, `fundWallet` will
+   * attempt to determine the correct server automatically. In other environments,
+   * or if you would like to customize the faucet host in devnet or testnet,
+   * you should provide the host using this option.
+   * @param options.faucetPath - A custom path for a faucet server. On devnet,
+   * testnet, AMM devnet, and HooksV3 testnet, `fundWallet` will
+   * attempt to determine the correct path automatically. In other environments,
+   * or if you would like to customize the faucet path in devnet or testnet,
+   * you should provide the path using this option.
+   * Ex: client.fundWallet(null,{'faucet.altnet.rippletest.net', '/accounts'})
+   * specifies a request to 'faucet.altnet.rippletest.net/accounts' to fund a new wallet.
+   * @param options.amount - A custom amount to fund, if undefined or null, the default amount will be 1000.
+   * @returns A Wallet on the Testnet or Devnet that contains some amount of XRP,
+   * and that wallet's balance in XRP.
+   * @throws When either Client isn't connected or unable to fund wallet address.
    */
-  public fundWallet = fundWallet
+  public async fundWallet(
+    this: Client,
+    wallet?: Wallet | null,
+    options: FundingOptions = {},
+  ): Promise<{
+    wallet: Wallet
+    balance: number
+  }> {
+    if (!this.isConnected()) {
+      throw new RippledError('Client not connected, cannot call faucet')
+    }
+    const existingWallet = Boolean(wallet)
+
+    // Generate a new Wallet if no existing Wallet is provided or its address is invalid to fund
+    const walletToFund =
+      wallet && isValidClassicAddress(wallet.classicAddress)
+        ? wallet
+        : Wallet.generate()
+
+    // Create the POST request body
+    const postBody: FaucetRequestBody = {
+      destination: walletToFund.classicAddress,
+      xrpAmount: options.amount,
+      usageContext: options.usageContext,
+      userAgent: 'xrpl.js',
+    }
+
+    let startingBalance = 0
+    if (existingWallet) {
+      try {
+        startingBalance = Number(
+          await this.getXrpBalance(walletToFund.classicAddress),
+        )
+      } catch {
+        /* startingBalance remains what it was previously */
+      }
+    }
+
+    return requestFunding(
+      options,
+      this,
+      startingBalance,
+      walletToFund,
+      postBody,
+    )
+  }
 }
 
 export { Client }