feat: add rippled API v2 support and use as default (#2656)

* add apiVersion support to requests and AccountInfoResponse v1/v2 types

* fix submitAndWait signature

* update docker container README

* update tests

* fix apiVersion param in wrong position of Client.request

* add integ tests

* update HISTORY.md

* fix request.api_version

* update RIPPLED_DOCKER_IMAGE to use v2.1.0

* refactor Client.request signature

* update rippled docker image

* fix Client.requestAll

* update rippled docker image to use v2.1.1

* update README

* use import type

* fix faucet; unrelated to PR

* add api_version v2 support and set as default while providing support for v1

* refactor: add apiVersion to Client

* resolve errors

* use DeliverMax for isPartialPayment check

* update fixtures

* resolve lint errors

* add API v1 support for isPartialPayment

* update CONTRIBUTING

* update accountTx JSDoc

* revert deleted JSDoc comments in accountTx

* update JSDoc for account_info response

* only use client.apiVersion in Client.request()

* add ledger_hash

* remove API v1 comment from v2 model

* update meta_blob JSDoc

* delete second AccountTxRequest matching

* add close_time_iso

* set close_time_iso as optional field

* add meta_blob to BaseResponse

* Revert "add meta_blob to BaseResponse"

This reverts commit 89794c6.

* use DEFAULT_API_VERSION throughout call stack

* improve JSDoc explanation of ledger_index

* remove this.apiVersion from getLedgerIndex

* refactor Client.request()

* refactor RequestManger.resolve()

* add TODO to fix TxResponse type assertion

* use @category ResponsesV1 for API v1 types

* refactor accountTxHasPartialPayment()

* remove TODO

packages/xrpl/HISTORY.md

@@ -5,8 +5,12 @@ Subscribe to [the **xrpl-announce** mailing list](https://groups.google.com/g/xr
 ## Unreleased
 * Remove references to the Hooks testnet faucet in the xrpl.js code repository.
 
+### BREAKING CHANGES
+* Use rippled api_version v2 as default while maintaining support for v1.
+
 ### Added
 * Add `nfts_by_issuer` clio-only API definition
+
 ## 3.1.0 (2024-06-03)
 
 ### BREAKING CHANGES

packages/xrpl/snippets/src/claimPayChannel.ts

@@ -56,7 +56,7 @@ async function claimPayChannel(): Promise<void> {
     Channel: hashes.hashPaymentChannel(
       wallet1.classicAddress,
       wallet2.classicAddress,
-      paymentChannelResponse.result.Sequence ?? 0,
+      paymentChannelResponse.result.tx_json.Sequence ?? 0,
     ),
     Amount: '100',
   }

packages/xrpl/snippets/src/sendEscrow.ts

@@ -63,7 +63,7 @@ async function sendEscrow(): Promise<void> {
     TransactionType: 'EscrowFinish',
     Account: wallet1.classicAddress,
     Owner: wallet1.classicAddress,
-    OfferSequence: Number(createEscrowResponse.result.Sequence),
+    OfferSequence: Number(createEscrowResponse.result.tx_json.Sequence),
   }
 
   await client.submit(finishTx, {

packages/xrpl/src/client/RequestManager.ts

@@ -4,6 +4,7 @@ import {
   TimeoutError,
   XrplError,
 } from '../errors'
+import type { APIVersion } from '../models'
 import { Response, RequestResponseMap } from '../models/methods'
 import { BaseRequest, ErrorResponse } from '../models/methods/baseMethod'
 
@@ -35,10 +36,10 @@ export default class RequestManager {
    * @param timer - The timer associated with the promise.
    * @returns A promise that resolves to the specified generic type.
    */
-  public async addPromise<R extends BaseRequest, T = RequestResponseMap<R>>(
-    newId: string | number,
-    timer: ReturnType<typeof setTimeout>,
-  ): Promise<T> {
+  public async addPromise<
+    R extends BaseRequest,
+    T = RequestResponseMap<R, APIVersion>,
+  >(newId: string | number, timer: ReturnType<typeof setTimeout>): Promise<T> {
     return new Promise<T>((resolve, reject) => {
       this.promisesAwaitingResponse.set(newId, {
         resolve,
@@ -55,7 +56,10 @@ export default class RequestManager {
    * @param response - Response to return.
    * @throws Error if no existing promise with the given ID.
    */
-  public resolve(id: string | number, response: Response): void {
+  public resolve(
+    id: string | number,
+    response: Partial<Response<APIVersion>>,
+  ): void {
     const promise = this.promisesAwaitingResponse.get(id)
     if (promise == null) {
       throw new XrplError(`No existing promise with id ${id}`, {
@@ -111,10 +115,10 @@ export default class RequestManager {
    * @returns Request ID, new request form, and the promise for resolving the request.
    * @throws XrplError if request with the same ID is already pending.
    */
-  public createRequest<R extends BaseRequest, T = RequestResponseMap<R>>(
-    request: R,
-    timeout: number,
-  ): [string | number, string, Promise<T>] {
+  public createRequest<
+    R extends BaseRequest,
+    T = RequestResponseMap<R, APIVersion>,
+  >(request: R, timeout: number): [string | number, string, Promise<T>] {
     let newId: string | number
     if (request.id == null) {
       newId = this.nextId
@@ -171,7 +175,9 @@ export default class RequestManager {
    * @param response - The response to handle.
    * @throws ResponseFormatError if the response format is invalid, RippledError if rippled returns an error.
    */
-  public handleResponse(response: Partial<Response | ErrorResponse>): void {
+  public handleResponse(
+    response: Partial<Response<APIVersion> | ErrorResponse>,
+  ): void {
     if (
       response.id == null ||
       !(typeof response.id === 'string' || typeof response.id === 'number')
@@ -205,8 +211,7 @@ export default class RequestManager {
     }
     // status no longer needed because error is thrown if status is not "success"
     delete response.status
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Must be a valid Response here
-    this.resolve(response.id, response as unknown as Response)
+    this.resolve(response.id, response)
   }
 
   /**

packages/xrpl/src/client/connection.ts

@@ -11,7 +11,7 @@ import {
   ConnectionError,
   XrplError,
 } from '../errors'
-import type { RequestResponseMap } from '../models'
+import type { APIVersion, RequestResponseMap } from '../models'
 import { BaseRequest } from '../models/methods/baseMethod'
 
 import ConnectionManager from './ConnectionManager'
@@ -267,6 +267,7 @@ export class Connection extends EventEmitter {
 
   /**
    * Disconnect the websocket, then connect again.
+   *
    */
   public async reconnect(): Promise<void> {
     /*
@@ -287,10 +288,10 @@ export class Connection extends EventEmitter {
    * @returns The response from the rippled server.
    * @throws NotConnectedError if the Connection isn't connected to a server.
    */
-  public async request<R extends BaseRequest, T = RequestResponseMap<R>>(
-    request: R,
-    timeout?: number,
-  ): Promise<T> {
+  public async request<
+    R extends BaseRequest,
+    T = RequestResponseMap<R, APIVersion>,
+  >(request: R, timeout?: number): Promise<T> {
     if (!this.shouldBeConnected || this.ws == null) {
       throw new NotConnectedError(JSON.stringify(request), request)
     }
@@ -468,6 +469,7 @@ export class Connection extends EventEmitter {
 
   /**
    * Starts a heartbeat to check the connection with the server.
+   *
    */
   private startHeartbeatInterval(): void {
     this.clearHeartbeatInterval()

packages/xrpl/src/client/index.ts

@@ -9,7 +9,12 @@ import {
   ValidationError,
   XrplError,
 } from '../errors'
-import type { LedgerIndex, Balance } from '../models/common'
+import {
+  APIVersion,
+  LedgerIndex,
+  Balance,
+  DEFAULT_API_VERSION,
+} from '../models/common'
 import {
   Request,
   // account methods
@@ -213,6 +218,12 @@ class Client extends EventEmitter<EventTypes> {
    */
   public buildVersion: string | undefined
 
+  /**
+   * API Version used by the server this client is connected to
+   *
+   */
+  public apiVersion: APIVersion = DEFAULT_API_VERSION
+
   /**
    * Creates a new Client with a websocket connection to a rippled server.
    *
@@ -307,7 +318,6 @@ class Client extends EventEmitter<EventTypes> {
    * additional request body parameters.
    *
    * @category Network
-   *
    * @param req - Request to send to the server.
    * @returns The response from the server.
    *
@@ -320,16 +330,20 @@ class Client extends EventEmitter<EventTypes> {
    * console.log(response)
    * ```
    */
-  public async request<R extends Request, T = RequestResponseMap<R>>(
-    req: R,
-  ): Promise<T> {
-    const response = await this.connection.request<R, T>({
+  public async request<
+    R extends Request,
+    V extends APIVersion = typeof DEFAULT_API_VERSION,
+    T = RequestResponseMap<R, V>,
+  >(req: R): Promise<T> {
+    const request = {
       ...req,
-      account: req.account
-        ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Must be string
-          ensureClassicAddress(req.account as string)
-        : undefined,
-    })
+      account:
+        typeof req.account === 'string'
+          ? ensureClassicAddress(req.account)
+          : undefined,
+      api_version: req.api_version ?? this.apiVersion,
+    }
+    const response = await this.connection.request<R, T>(request)
 
     // mutates `response` to add warnings
     handlePartialPayment(req.command, response)
@@ -438,9 +452,10 @@ class Client extends EventEmitter<EventTypes> {
    * const allResponses = await client.requestAll({ command: 'transaction_data' });
    * console.log(allResponses);
    */
+
   public async requestAll<
     T extends MarkerRequest,
-    U = RequestAllResponseMap<T>,
+    U = RequestAllResponseMap<T, APIVersion>,
   >(request: T, collect?: string): Promise<U[]> {
     /*
      * The data under collection is keyed based on the command. Fail if command
@@ -468,7 +483,7 @@ class Client extends EventEmitter<EventTypes> {
       // 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 MarkerResponse).result
+      const singleResult = (singleResponse as MarkerResponse<APIVersion>).result
       if (!(collectKey in singleResult)) {
         throw new XrplError(`${collectKey} not in result`)
       }

packages/xrpl/src/client/partialPayment.ts

@@ -2,13 +2,16 @@ 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, APIVersion, DEFAULT_API_VERSION } 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 type { TransactionMetadata } from '../models/transactions/metadata'
@@ -63,7 +66,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,31 +79,46 @@ 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':
       return txHasPartialPayment(response as TxResponse)
     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 +133,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.

packages/xrpl/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 {
@@ -104,6 +108,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.
    */