feat: add rippled API v2 support and use as default

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,7 @@ 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: Response<APIVersion>): void {
     const promise = this.promisesAwaitingResponse.get(id)
     if (promise == null) {
       throw new XrplError(`No existing promise with id ${id}`, {
@@ -111,10 +112,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 +172,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')
@@ -206,7 +209,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 as unknown as Response<APIVersion>)
   }
 
   /**

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
@@ -28,6 +33,7 @@ import {
   LedgerDataRequest,
   LedgerDataResponse,
   TxResponse,
+  LedgerRequest,
 } from '../models/methods'
 import type {
   RequestResponseMap,
@@ -213,6 +219,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.
    *
@@ -306,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.
    *
@@ -319,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,
-    })
+      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)
@@ -437,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
@@ -467,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`)
       }
@@ -1037,9 +1053,13 @@ class Client extends EventEmitter<EventTypes> {
    * ```
    */
   public async getLedgerIndex(): Promise<number> {
-    const ledgerResponse = await this.request({
+    const ledgerResponse = await this.request<
+      LedgerRequest,
+      typeof this.apiVersion
+    >({
       command: 'ledger',
       ledger_index: 'validated',
+      api_version: this.apiVersion,
     })
     return ledgerResponse.result.ledger_index
   }

packages/xrpl/src/client/partialPayment.ts

@@ -7,7 +7,7 @@ import type {
   TransactionStream,
   TxResponse,
 } from '..'
-import type { Amount } from '../models/common'
+import type { Amount, APIVersion } from '../models/common'
 import type { RequestResponseMap } from '../models/methods'
 import { BaseRequest, BaseResponse } from '../models/methods/baseMethod'
 import { PaymentFlags, Transaction } from '../models/transactions'
@@ -63,7 +63,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,7 +76,7 @@ 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 {
@@ -82,14 +85,17 @@ function txEntryHasPartialPayment(response: TransactionEntryResponse): boolean {
 
 function accountTxHasPartialPayment(response: AccountTxResponse): boolean {
   const { transactions } = response.result
-  const foo = transactions.some((tx) => isPartialPayment(tx.tx, tx.meta))
+  const foo = transactions.some((tx) =>
+    // API v2 returns tx_json, API v1 returns tx
+    isPartialPayment(tx.tx_json ?? tx.tx, tx.meta),
+  )
   return foo
 }
 
-function hasPartialPayment<R extends BaseRequest, T = RequestResponseMap<R>>(
-  command: string,
-  response: T,
-): boolean {
+function hasPartialPayment<
+  R extends BaseRequest,
+  T = RequestResponseMap<R, APIVersion>,
+>(command: string, response: T): boolean {
   /* eslint-disable @typescript-eslint/consistent-type-assertions -- Request type is known at runtime from command */
   switch (command) {
     case 'tx':
@@ -112,7 +118,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.
    */

packages/xrpl/src/models/ledger/Ledger.ts

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