xrpl 3.0.0 → 4.0.0

package/src/models/transactions/metadata.ts

@@ -40,6 +40,7 @@ export interface DeletedNode {
   DeletedNode: {
     LedgerEntryType: string
     LedgerIndex: string
+    PreviousFields?: { [field: string]: unknown }
     FinalFields: { [field: string]: unknown }
   }
 }

package/src/models/transactions/oracleDelete.ts

@@ -0,0 +1,32 @@
+import {
+  BaseTransaction,
+  isNumber,
+  validateBaseTransaction,
+  validateRequiredField,
+} from './common'
+
+/**
+ * Delete an Oracle ledger entry.
+ *
+ * @category Transaction Models
+ */
+export interface OracleDelete extends BaseTransaction {
+  TransactionType: 'OracleDelete'
+
+  /**
+   * A unique identifier of the price oracle for the Account.
+   */
+  OracleDocumentID: number
+}
+
+/**
+ * Verify the form and type of a OracleDelete at runtime.
+ *
+ * @param tx - A OracleDelete Transaction.
+ * @throws When the OracleDelete is malformed.
+ */
+export function validateOracleDelete(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'OracleDocumentID', isNumber)
+}

package/src/models/transactions/oracleSet.ts

@@ -0,0 +1,176 @@
+import { ValidationError } from '../../errors'
+import { PriceData } from '../common'
+
+import {
+  BaseTransaction,
+  isNumber,
+  isString,
+  validateBaseTransaction,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
+
+const PRICE_DATA_SERIES_MAX_LENGTH = 10
+const SCALE_MAX = 10
+
+/**
+ * Creates a new Oracle ledger entry or updates the fields of an existing one, using the Oracle ID.
+ *
+ * The oracle provider must complete these steps before submitting this transaction:
+ * 1. Create or own the XRPL account in the Owner field and have enough XRP to meet the reserve and transaction fee requirements.
+ * 2. Publish the XRPL account public key, so it can be used for verification by dApps.
+ * 3. Publish a registry of available price oracles with their unique OracleDocumentID.
+ *
+ * @category Transaction Models
+ */
+export interface OracleSet extends BaseTransaction {
+  TransactionType: 'OracleSet'
+
+  /**
+   * A unique identifier of the price oracle for the Account.
+   */
+  OracleDocumentID: number
+
+  /**
+   * The time the data was last updated, represented as a unix timestamp in seconds.
+   */
+  LastUpdateTime: number
+
+  /**
+   * An array of up to 10 PriceData objects, each representing the price information
+   * for a token pair. More than five PriceData objects require two owner reserves.
+   */
+  PriceDataSeries: PriceData[]
+
+  /**
+   * An arbitrary value that identifies an oracle provider, such as Chainlink, Band,
+   * or DIA. This field is a string, up to 256 ASCII hex encoded characters (0x20-0x7E).
+   * This field is required when creating a new Oracle ledger entry, but is optional for updates.
+   */
+  Provider?: string
+
+  /**
+   * An optional Universal Resource Identifier to reference price data off-chain. This field is limited to 256 bytes.
+   */
+  URI?: string
+
+  /**
+   * Describes the type of asset, such as "currency", "commodity", or "index". This field is a string, up to 16 ASCII
+   * hex encoded characters (0x20-0x7E). This field is required when creating a new Oracle ledger entry, but is optional
+   * for updates.
+   */
+  AssetClass?: string
+}
+
+/**
+ * Verify the form and type of a OracleSet at runtime.
+ *
+ * @param tx - A OracleSet Transaction.
+ * @throws When the OracleSet is malformed.
+ */
+// eslint-disable-next-line max-lines-per-function -- necessary to validate many fields
+export function validateOracleSet(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'OracleDocumentID', isNumber)
+
+  validateRequiredField(tx, 'LastUpdateTime', isNumber)
+
+  validateOptionalField(tx, 'Provider', isString)
+
+  validateOptionalField(tx, 'URI', isString)
+
+  validateOptionalField(tx, 'AssetClass', isString)
+
+  // eslint-disable-next-line max-lines-per-function -- necessary to validate many fields
+  validateRequiredField(tx, 'PriceDataSeries', (value) => {
+    if (!Array.isArray(value)) {
+      throw new ValidationError('OracleSet: PriceDataSeries must be an array')
+    }
+
+    if (value.length > PRICE_DATA_SERIES_MAX_LENGTH) {
+      throw new ValidationError(
+        `OracleSet: PriceDataSeries must have at most ${PRICE_DATA_SERIES_MAX_LENGTH} PriceData objects`,
+      )
+    }
+
+    // TODO: add support for handling inner objects easier (similar to validateRequiredField/validateOptionalField)
+    for (const priceData of value) {
+      if (typeof priceData !== 'object') {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must be an array of objects',
+        )
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+      if (priceData.PriceData == null) {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must have a `PriceData` object',
+        )
+      }
+
+      // check if priceData only has PriceData
+      if (Object.keys(priceData).length !== 1) {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must only have a single PriceData object',
+        )
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+      if (typeof priceData.PriceData.BaseAsset !== 'string') {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must have a `BaseAsset` string',
+        )
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+      if (typeof priceData.PriceData.QuoteAsset !== 'string') {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must have a `QuoteAsset` string',
+        )
+      }
+
+      // Either AssetPrice and Scale are both present or both excluded
+      if (
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        (priceData.PriceData.AssetPrice == null) !==
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        (priceData.PriceData.Scale == null)
+      ) {
+        throw new ValidationError(
+          'OracleSet: PriceDataSeries must have both `AssetPrice` and `Scale` if any are present',
+        )
+      }
+
+      if (
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        'AssetPrice' in priceData.PriceData &&
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        !isNumber(priceData.PriceData.AssetPrice)
+      ) {
+        throw new ValidationError('OracleSet: invalid field AssetPrice')
+      }
+
+      if (
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        'Scale' in priceData.PriceData &&
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        !isNumber(priceData.PriceData.Scale)
+      ) {
+        throw new ValidationError('OracleSet: invalid field Scale')
+      }
+
+      if (
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        priceData.PriceData.Scale < 0 ||
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- we are validating the type
+        priceData.PriceData.Scale > SCALE_MAX
+      ) {
+        throw new ValidationError(
+          `OracleSet: Scale must be in range 0-${SCALE_MAX}`,
+        )
+      }
+    }
+    return true
+  })
+}

package/src/models/transactions/payment.ts

@@ -26,7 +26,7 @@ export enum PaymentFlags {
    * This is intended to force the transaction to take arbitrage opportunities.
    * Most clients do not need this.
    */
-  tfNoDirectRipple = 0x00010000,
+  tfNoRippleDirect = 0x00010000,
   /**
    * If the specified Amount cannot be sent without spending more than SendMax,
    * reduce the received amount instead of failing outright. See Partial.
@@ -88,7 +88,7 @@ export interface PaymentFlagsInterface extends GlobalFlags {
    * This is intended to force the transaction to take arbitrage opportunities.
    * Most clients do not need this.
    */
-  tfNoDirectRipple?: boolean
+  tfNoRippleDirect?: boolean
   /**
    * If the specified Amount cannot be sent without spending more than SendMax,
    * reduce the received amount instead of failing outright. See Partial.

package/src/models/transactions/transaction.ts

@@ -43,6 +43,8 @@ import {
 import { NFTokenMint, validateNFTokenMint } from './NFTokenMint'
 import { OfferCancel, validateOfferCancel } from './offerCancel'
 import { OfferCreate, validateOfferCreate } from './offerCreate'
+import { OracleDelete, validateOracleDelete } from './oracleDelete'
+import { OracleSet, validateOracleSet } from './oracleSet'
 import { Payment, validatePayment } from './payment'
 import {
   PaymentChannelClaim,
@@ -120,6 +122,8 @@ export type SubmittableTransaction =
   | NFTokenMint
   | OfferCancel
   | OfferCreate
+  | OracleDelete
+  | OracleSet
   | Payment
   | PaymentChannelClaim
   | PaymentChannelCreate
@@ -330,6 +334,14 @@ export function validate(transaction: Record<string, unknown>): void {
       validateOfferCreate(tx)
       break
 
+    case 'OracleDelete':
+      validateOracleDelete(tx)
+      break
+
+    case 'OracleSet':
+      validateOracleSet(tx)
+      break
+
     case 'Payment':
       validatePayment(tx)
       break

package/src/sugar/autofill.ts

@@ -1,7 +1,7 @@
 import BigNumber from 'bignumber.js'
 import { xAddressToClassicAddress, isValidXAddress } from 'ripple-address-codec'
 
-import type { Client } from '..'
+import { type Client } from '..'
 import { ValidationError, XrplError } from '../errors'
 import { AccountInfoRequest, AccountObjectsRequest } from '../models/methods'
 import { Transaction } from '../models/transactions'
@@ -17,7 +17,6 @@ const LEDGER_OFFSET = 20
 // Mainnet and testnet are exceptions. More context: https://github.com/XRPLF/rippled/pull/4370
 const RESTRICTED_NETWORKS = 1024
 const REQUIRED_NETWORKID_VERSION = '1.11.0'
-const HOOKS_TESTNET_ID = 21338
 
 /**
  * Determines whether the source rippled version is not later than the target rippled version.
@@ -87,8 +86,7 @@ function isNotLaterRippledVersion(source: string, target: string): boolean {
 
 /**
  * Determine if the transaction required a networkID to be valid.
- * Transaction needs networkID if later than restricted ID and either the network is hooks testnet
- * or build version is >= 1.11.0
+ * Transaction needs networkID if later than restricted ID and build version is >= 1.11.0
  *
  * @param client -- The connected client.
  * @returns True if required networkID, false otherwise.
@@ -99,12 +97,8 @@ export function txNeedsNetworkID(client: Client): boolean {
     client.networkID > RESTRICTED_NETWORKS
   ) {
     if (
-      (client.buildVersion &&
-        isNotLaterRippledVersion(
-          REQUIRED_NETWORKID_VERSION,
-          client.buildVersion,
-        )) ||
-      client.networkID === HOOKS_TESTNET_ID
+      client.buildVersion &&
+      isNotLaterRippledVersion(REQUIRED_NETWORKID_VERSION, client.buildVersion)
     ) {
       return true
     }

package/src/sugar/getFeeXrp.ts

@@ -1,6 +1,6 @@
 import BigNumber from 'bignumber.js'
 
-import type { Client } from '..'
+import { type Client } from '..'
 import { XrplError } from '../errors'
 
 const NUM_DECIMAL_PLACES = 6
@@ -20,8 +20,11 @@ export default async function getFeeXrp(
 ): Promise<string> {
   const feeCushion = cushion ?? client.feeCushion
 
-  const serverInfo = (await client.request({ command: 'server_info' })).result
-    .info
+  const serverInfo = (
+    await client.request({
+      command: 'server_info',
+    })
+  ).result.info
 
   const baseFee = serverInfo.validated_ledger?.base_fee_xrp
 

package/src/sugar/submit.ts

@@ -10,7 +10,7 @@ import type {
 } from '..'
 import { ValidationError, XrplError } from '../errors'
 import { Signer } from '../models/common'
-import { TxRequest, TxResponse } from '../models/methods'
+import { TxResponse } from '../models/methods'
 import { BaseTransaction } from '../models/transactions/common'
 
 /** Approximate time for a ledger to close, in milliseconds */
@@ -129,7 +129,7 @@ export async function waitForFinalTransactionOutcome<
   }
 
   const txResponse = await client
-    .request<TxRequest, TxResponse<T>>({
+    .request({
       command: 'tx',
       transaction: txHash,
     })
@@ -153,7 +153,9 @@ export async function waitForFinalTransactionOutcome<
     })
 
   if (txResponse.result.validated) {
-    return txResponse
+    // TODO: resolve the type assertion below
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- we know that txResponse is of type TxResponse
+    return txResponse as TxResponse<T>
   }
 
   return waitForFinalTransactionOutcome<T>(

package/src/utils/hashes/hashLedger.ts

@@ -8,8 +8,9 @@ import BigNumber from 'bignumber.js'
 import { decode, encode } from 'ripple-binary-codec'
 
 import { ValidationError, XrplError } from '../../errors'
-import type { Ledger } from '../../models/ledger'
+import { APIVersion } from '../../models'
 import { LedgerEntry } from '../../models/ledger'
+import { LedgerVersionMap } from '../../models/ledger/Ledger'
 import { Transaction, TransactionMetadata } from '../../models/transactions'
 
 import HashPrefix from './HashPrefix'
@@ -99,7 +100,9 @@ export function hashSignedTx(tx: Transaction | string): string {
  * @returns The hash of the ledger.
  * @category Utilities
  */
-export function hashLedgerHeader(ledgerHeader: Ledger): string {
+export function hashLedgerHeader(
+  ledgerHeader: LedgerVersionMap<APIVersion>,
+): string {
   const prefix = HashPrefix.LEDGER.toString(HEX).toUpperCase()
 
   const ledger =
@@ -158,7 +161,7 @@ export function hashStateTree(entries: LedgerEntry[]): string {
 }
 
 function computeTransactionHash(
-  ledger: Ledger,
+  ledger: LedgerVersionMap<APIVersion>,
   options: HashLedgerHeaderOptions,
 ): string {
   const { transaction_hash } = ledger
@@ -188,7 +191,7 @@ function computeTransactionHash(
 }
 
 function computeStateHash(
-  ledger: Ledger,
+  ledger: LedgerVersionMap<APIVersion>,
   options: HashLedgerHeaderOptions,
 ): string {
   const { account_hash } = ledger
@@ -222,7 +225,7 @@ function computeStateHash(
  * @category Utilities
  */
 function hashLedger(
-  ledger: Ledger,
+  ledger: LedgerVersionMap<APIVersion>,
   options: {
     computeTreeHashes?: boolean
   } = {},

package/src/utils/index.ts

@@ -23,6 +23,7 @@ import {
 } from 'ripple-binary-codec'
 import { verify as verifyKeypairSignature } from 'ripple-keypairs'
 
+import type { APIVersion } from '../models'
 import { LedgerEntry } from '../models/ledger'
 import { Response } from '../models/methods'
 import { PaymentChannelClaim } from '../models/transactions/paymentChannelClaim'
@@ -157,7 +158,7 @@ function isValidAddress(address: string): boolean {
  * @returns Whether the response has more pages of data.
  * @category Utilities
  */
-function hasNextPage(response: Response): boolean {
+function hasNextPage(response: Response<APIVersion>): boolean {
   // eslint-disable-next-line @typescript-eslint/dot-notation -- only checking if it exists
   return Boolean(response.result['marker'])
 }