xrpl 2.10.0 → 2.11.0

package/src/models/methods/accountTx.ts

@@ -0,0 +1,109 @@
+import { ResponseOnlyTxInfo } from '../common'
+import { Transaction, TransactionMetadata } from '../transactions'
+
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+/**
+ * The account_tx method retrieves a list of transactions that involved the
+ * specified account. Expects a response in the form of a {@link
+ * AccountTxResponse}.
+ *
+ * @category Requests
+ */
+export interface AccountTxRequest extends BaseRequest, LookupByLedgerRequest {
+  command: 'account_tx'
+  /** A unique identifier for the account, most commonly the account's address. */
+  account: string
+  /**
+   * Use to specify the earliest ledger to include transactions from. A value
+   * of -1 instructs the server to use the earliest validated ledger version
+   * available.
+   */
+  ledger_index_min?: number
+  /**
+   * Use to specify the most recent ledger to include transactions from. A
+   * value of -1 instructs the server to use the most recent validated ledger
+   * version available.
+   */
+  ledger_index_max?: number
+  /**
+   * If true, return transactions as hex strings instead of JSON. The default is
+   * false.
+   */
+  binary?: boolean
+  /**
+   * If true, returns values indexed with the oldest ledger first. Otherwise,
+   * the results are indexed with the newest ledger first.
+   */
+  forward?: boolean
+  /**
+   * Default varies. Limit the number of transactions to retrieve. The server
+   * is not required to honor this value.
+   */
+  limit?: number
+  /**
+   * Value from a previous paginated response. Resume retrieving data where
+   * that response left off. This value is stable even if there is a change in
+   * the server's range of available ledgers.
+   */
+  marker?: unknown
+}
+
+export interface AccountTxTransaction {
+  /** The ledger index of the ledger version that included this transaction. */
+  ledger_index: number
+  /**
+   * If binary is True, then this is a hex string of the transaction metadata.
+   * Otherwise, the transaction metadata is included in JSON format.
+   */
+  meta: string | TransactionMetadata
+  /** JSON object defining the transaction. */
+  tx?: Transaction & ResponseOnlyTxInfo
+  /** Unique hashed String representing the transaction. */
+  tx_blob?: string
+  /**
+   * Whether or not the transaction is included in a validated ledger. Any
+   * transaction not yet in a validated ledger is subject to change.
+   */
+  validated: boolean
+}
+
+/**
+ * Expected response from an {@link AccountTxRequest}.
+ *
+ * @category Responses
+ */
+export interface AccountTxResponse extends BaseResponse {
+  result: {
+    /** Unique Address identifying the related account. */
+    account: string
+    /**
+     * The ledger index of the earliest ledger actually searched for
+     * transactions.
+     */
+    ledger_index_min: number
+    /**
+     * The ledger index of the most recent ledger actually searched for
+     * transactions.
+     */
+    ledger_index_max: number
+    /** The limit value used in the request. */
+    limit: number
+    /**
+     * Server-defined value indicating the response is paginated. Pass this
+     * to the next call to resume where this call left off.
+     */
+    marker?: unknown
+    /**
+     * Array of transactions matching the request's criteria, as explained
+     * below.
+     */
+    transactions: AccountTxTransaction[]
+    /**
+     * If included and set to true, the information in this response comes from
+     * a validated ledger version. Otherwise, the information is subject to
+     * change.
+     */
+    validated?: boolean
+  }
+}

package/src/models/methods/ammInfo.ts

@@ -0,0 +1,145 @@
+import { Amount, Currency, IssuedCurrencyAmount } from '../common'
+
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The `amm_info` method gets information about an Automated Market Maker (AMM) instance.
+ * Returns an {@link AMMInfoResponse}.
+ *
+ * @category Requests
+ */
+export interface AMMInfoRequest extends BaseRequest {
+  command: 'amm_info'
+
+  /**
+   * One of the assets of the AMM pool to look up.
+   */
+  asset: Currency
+
+  /**
+   * The other asset of the AMM pool.
+   */
+  asset2: Currency
+}
+
+/**
+ * Response expected from an {@link AMMInfoRequest}.
+ *
+ * @category Responses
+ */
+export interface AMMInfoResponse extends BaseResponse {
+  result: {
+    amm: {
+      /**
+       * The address of the AMM Account.
+       */
+      account: string
+
+      /**
+       * The total amount of one asset in the AMM's pool.
+       * (Note: This could be asset or asset2 from the request)
+       */
+      amount: Amount
+
+      /**
+       * The total amount of the other asset in the AMM's pool.
+       * (Note: This could be asset or asset2 from the request)
+       */
+      amount2: Amount
+
+      /**
+       * (Omitted for XRP) If true, the amount currency is currently frozen for asset.
+       */
+      asset_frozen?: boolean
+
+      /**
+       * (Omitted for XRP) If true, the amount currency is currently frozen for asset2.
+       */
+      asset2_frozen?: boolean
+
+      /**
+       * (May be omitted) An Auction Slot Object describing the current auction slot holder, if there is one.
+       */
+      auction_slot?: {
+        /**
+         * The address of the account that owns the auction slot.
+         */
+        account: string
+
+        /**
+         * A list of additional accounts that the auction slot holder has designated as being eligible
+         * of the discounted trading fee.
+         * Each member of this array is an object with one field, account, containing the address of the designated account.
+         */
+        auth_accounts: Array<{
+          account: string
+        }>
+
+        /**
+         * The discounted trading fee that applies to the auction slot holder, and any eligible accounts
+         * when trading against this AMM.
+         * This is always 0.
+         */
+        discounted_fee: number
+
+        /**
+         * The ISO 8601 UTC timestamp after which this auction slot expires.
+         * After expired, the auction slot does not apply (but the data can remain in the ledger
+         * until another transaction replaces it or cleans it up).
+         */
+        expiration: string
+
+        /**
+         * The amount, in LP Tokens, that the auction slot holder paid to win the auction slot.
+         * This affects the price to outbid the current slot holder.
+         */
+        price: Amount
+
+        /**
+         * The current 72-minute time interval this auction slot is in, from 0 to 19.
+         * The auction slot expires after 24 hours (20 intervals of 72 minutes)
+         * and affects the cost to outbid the current holder and how much the current holder is refunded if someone outbids them.
+         */
+        time_interval: number
+      }
+
+      /**
+       * The total amount of this AMM's LP Tokens outstanding.
+       */
+      lp_token: IssuedCurrencyAmount
+
+      /**
+       * The AMM's current trading fee, in units of 1/100,000; a value of 1 is equivalent to a 0.001% fee.
+       */
+      trading_fee: number
+
+      /**
+       * (May be omitted) The current votes for the AMM's trading fee, as Vote Slot Objects.
+       */
+      vote_slots?: Array<{
+        account: string
+        trading_fee: number
+        vote_weight: number
+      }>
+    }
+
+    /**
+     * The identifying hash of the ledger that was used to generate this
+     * response.
+     */
+    ledger_hash?: string
+
+    /**
+     * The ledger index of the ledger version that was used to generate this
+     * response.
+     */
+    ledger_index?: number
+
+    /**
+     * If included and set to true, the information in this response comes from
+     * a validated ledger version. Otherwise, the information is subject to
+     * change.
+     */
+    validated?: boolean
+  }
+}

package/src/models/methods/baseMethod.ts

@@ -0,0 +1,58 @@
+import { LedgerIndex } from '../common'
+
+import type { Request } from '.'
+
+export interface BaseRequest {
+  [x: string]: unknown
+  /**
+   * A unique value to identify this request. The response to this request uses
+   * the same id field. This way, even if responses arrive out of order, you
+   * know which request prompted which response.
+   */
+  id?: number | string
+  /** The name of the API method. */
+  command: string
+  /** The API version to use. If omitted, use version 1. */
+  api_version?: number
+}
+
+export interface LookupByLedgerRequest {
+  /** A 20-byte hex string for the ledger version to use. */
+  ledger_hash?: string
+  /** The ledger index of the ledger to use, or a shortcut string. */
+  ledger_index?: LedgerIndex
+}
+
+export interface ResponseWarning {
+  id: number
+  message: string
+  details?: { [key: string]: string }
+}
+
+export interface BaseResponse {
+  id: number | string
+  status?: 'success' | string
+  type: 'response' | string
+  result: unknown
+  warning?: 'load'
+  warnings?: ResponseWarning[]
+  forwarded?: boolean
+  api_version?: number
+}
+
+/**
+ * The shape of an error response from rippled. xrpl.js handles rejections by
+ * throwing, and allowing the user to handle in the catch block of a promise.
+ *
+ * @category Responses
+ */
+export interface ErrorResponse {
+  id: number | string
+  status: 'error'
+  type: 'response' | string
+  error: string
+  error_code?: string
+  error_message?: string
+  request: Request
+  api_version?: number
+}

package/src/models/methods/bookOffers.ts

@@ -0,0 +1,96 @@
+import { Amount } from '../common'
+import { Offer } from '../ledger'
+
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+export interface BookOfferCurrency {
+  currency: string
+  issuer?: string
+}
+
+/**
+ * The book_offers method retrieves a list of offers, also known as the order.
+ * Book, between two currencies. Returns an {@link BookOffersResponse}.
+ *
+ * @category Requests
+ */
+export interface BookOffersRequest extends BaseRequest, LookupByLedgerRequest {
+  command: 'book_offers'
+  /**
+   * If provided, the server does not provide more than this many offers in the
+   * results. The total number of results returned may be fewer than the limit,
+   * because the server omits unfunded offers.
+   */
+  limit?: number
+  /**
+   * The Address of an account to use as a perspective. Unfunded offers placed
+   * by this account are always included in the response.
+   */
+  taker?: string
+  /**
+   * Specification of which currency the account taking the offer would
+   * receive, as an object with currency and issuer fields (omit issuer for
+   * XRP), like currency amounts.
+   */
+  taker_gets: BookOfferCurrency
+  /**
+   * Specification of which currency the account taking the offer would pay, as
+   * an object with currency and issuer fields (omit issuer for XRP), like
+   * currency amounts.
+   */
+  taker_pays: BookOfferCurrency
+}
+
+export interface BookOffer extends Offer {
+  /**
+   * Amount of the TakerGets currency the side placing the offer has available
+   * to be traded. (XRP is represented as drops; any other currency is
+   * represented as a decimal value.) If a trader has multiple offers in the
+   * same book, only the highest-ranked offer includes this field.
+   */
+  owner_funds?: string
+  /**
+   * The maximum amount of currency that the taker can get, given the funding
+   * status of the offer.
+   */
+  taker_gets_funded?: Amount
+  /**
+   * The maximum amount of currency that the taker would pay, given the funding
+   * status of the offer.
+   */
+  taker_pays_funded?: Amount
+  /**
+   * The exchange rate, as the ratio taker_pays divided by taker_gets. For
+   * fairness, offers that have the same quality are automatically taken
+   * first-in, first-out.
+   */
+  quality?: string
+}
+
+/**
+ * Expected response from a {@link BookOffersRequest}.
+ *
+ * @category Responses
+ */
+export interface BookOffersResponse extends BaseResponse {
+  result: {
+    /**
+     * The ledger index of the current in-progress ledger version, which was
+     * used to retrieve this information.
+     */
+    ledger_current_index?: number
+    /**
+     * The ledger index of the ledger version that was used when retrieving
+     * this data, as requested.
+     */
+    ledger_index?: number
+    /**
+     * The identifying hash of the ledger version that was used when retrieving
+     * this data, as requested.
+     */
+    ledger_hash?: string
+    /** Array of offer objects, each of which has the fields of an Offer object. */
+    offers: BookOffer[]
+    validated?: boolean
+  }
+}

package/src/models/methods/channelVerify.ts

@@ -0,0 +1,41 @@
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The `channel_verify` method checks the validity of a signature that can be
+ * used to redeem a specific amount of XRP from a payment channel. Expects a
+ * response in the form of a {@link ChannelVerifyResponse}.
+ *
+ * @category Requests
+ */
+export interface ChannelVerifyRequest extends BaseRequest {
+  command: 'channel_verify'
+  /** The amount of XRP, in drops, the provided signature authorizes. */
+  amount: string
+  /**
+   * The Channel ID of the channel that provides the XRP. This is a
+   * 64-character hexadecimal string.
+   */
+  channel_id: string
+  /**
+   * The public key of the channel and the key pair that was used to create the
+   * signature, in hexadecimal or the XRP Ledger's base58 format.
+   */
+  public_key: string
+  /** The signature to verify, in hexadecimal. */
+  signature: string
+}
+
+/**
+ * Response expected from an {@link ChannelVerifyRequest}.
+ *
+ * @category Responses
+ */
+export interface ChannelVerifyResponse extends BaseResponse {
+  result: {
+    /**
+     * If true, the signature is valid for the stated amount, channel, and
+     * public key.
+     */
+    signature_verified: boolean
+  }
+}

package/src/models/methods/depositAuthorized.ts

@@ -0,0 +1,56 @@
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+/**
+ * The deposit_authorized command indicates whether one account is authorized to
+ * send payments directly to another. Expects a response in the form of a {@link
+ * DepositAuthorizedResponse}.
+ *
+ * @category Requests
+ */
+export interface DepositAuthorizedRequest
+  extends BaseRequest,
+    LookupByLedgerRequest {
+  command: 'deposit_authorized'
+  /** The sender of a possible payment. */
+  source_account: string
+  /** The recipient of a possible payment. */
+  destination_account: string
+}
+
+/**
+ * Expected response from a {@link DepositAuthorizedRequest}.
+ *
+ * @category Responses
+ */
+export interface DepositAuthorizedResponse extends BaseResponse {
+  result: {
+    /**
+     * Whether the specified source account is authorized to send payments
+     * directly to the destination account. If true, either the destination
+     * account does not require Deposit Authorization or the source account is
+     * preauthorized.
+     */
+    deposit_authorized: boolean
+    /** The destination account specified in the request. */
+    destination_account: string
+    /**
+     * The identifying hash of the ledger that was used to generate this
+     * Response.
+     */
+    ledger_hash?: string
+    /**
+     * The ledger index of the ledger version that was used to generate this
+     * Response.
+     */
+    ledger_index?: number
+    /**
+     * The ledger index of the current in-progress ledger version, which was
+     * used to generate this response.
+     */
+    ledger_current_index?: number
+    /** The source account specified in the request. */
+    source_account: string
+    /** If true, the information comes from a validated ledger version. */
+    validated?: boolean
+  }
+}

package/src/models/methods/fee.ts

@@ -0,0 +1,91 @@
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The `fee` command reports the current state of the open-ledger requirements
+ * for the transaction cost. This requires the FeeEscalation amendment to be
+ * enabled. Expects a response in the form of a {@link FeeResponse}.
+ *
+ * @example
+ * ```ts
+ * const feeRequest: FeeRequest = {
+ *  command: 'fee'
+ * }
+ * ```
+ *
+ * @category Requests
+ */
+export interface FeeRequest extends BaseRequest {
+  command: 'fee'
+}
+
+/**
+ * Response expected from a {@link FeeRequest}.
+ *
+ * @category Responses
+ */
+export interface FeeResponse extends BaseResponse {
+  result: {
+    /** Number of transactions provisionally included in the in-progress ledger. */
+    current_ledger_size: string
+    /** Number of transactions currently queued for the next ledger. */
+    current_queue_size: string
+    drops: {
+      /**
+       * The transaction cost required for a reference transaction to be
+       * included in a ledger under minimum load, represented in drops of XRP.
+       */
+      base_fee: string
+      /**
+       * An approximation of the median transaction cost among transactions.
+       * Included in the previous validated ledger, represented in drops of XRP.
+       */
+      median_fee: string
+      /**
+       * The minimum transaction cost for a reference transaction to be queued
+       * for a later ledger, represented in drops of XRP. If greater than
+       * base_fee, the transaction queue is full.
+       */
+      minimum_fee: string
+      /**
+       * The minimum transaction cost that a reference transaction must pay to
+       * be included in the current open ledger, represented in drops of XRP.
+       */
+      open_ledger_fee: string
+    }
+    /**
+     * The approximate number of transactions expected to be included in the
+     * current ledger. This is based on the number of transactions in the
+     * previous ledger.
+     */
+    expected_ledger_size: string
+    /** The Ledger Index of the current open ledger these stats describe. */
+    ledger_current_index: number
+    levels: {
+      /**
+       * The median transaction cost among transactions in the previous
+       * validated ledger, represented in fee levels.
+       */
+      median_level: string
+      /**
+       * The minimum transaction cost required to be queued for a future
+       * ledger, represented in fee levels.
+       */
+      minimum_level: string
+      /**
+       * The minimum transaction cost required to be included in the current
+       * open ledger, represented in fee levels.
+       */
+      open_ledger_level: string
+      /**
+       * The equivalent of the minimum transaction cost, represented in fee
+       * levels.
+       */
+      reference_level: string
+    }
+    /**
+     * The maximum number of transactions that the transaction queue can
+     * currently hold.
+     */
+    max_queue_size: string
+  }
+}

package/src/models/methods/gatewayBalances.ts

@@ -0,0 +1,85 @@
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+/**
+ * The gateway_balances command calculates the total balances issued by a given
+ * account, optionally excluding amounts held by operational addresses. Expects
+ * a response in the form of a {@link GatewayBalancesResponse}.
+ *
+ * @example
+ * ```ts
+ * const gatewayBalances: GatewayBalanceRequest = {
+ *   "id": "example_gateway_balances_1",
+ *   "command": "gateway_balances",
+ *   "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
+ *   "strict": true,
+ *   "hotwallet": ["rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ","ra7JkEzrgeKHdzKgo4EUUVBnxggY4z37kt"],
+ *   "ledger_index": "validated"
+ * }
+ * ```
+ *
+ * @category Requests
+ */
+export interface GatewayBalancesRequest
+  extends BaseRequest,
+    LookupByLedgerRequest {
+  command: 'gateway_balances'
+  /** The Address to check. This should be the issuing address. */
+  account: string
+  /**
+   * If true, only accept an address or public key for the account parameter.
+   * Defaults to false.
+   */
+  strict?: boolean
+  /**
+   * An operational address to exclude from the balances issued, or an array of
+   * Such addresses.
+   */
+  hotwallet?: string | string[]
+}
+
+export interface GatewayBalance {
+  currency: string
+  value: string
+}
+
+/**
+ * Expected response from a {@link GatewayBalancesRequest}.
+ *
+ * @category Responses
+ */
+export interface GatewayBalancesResponse extends BaseResponse {
+  result: {
+    /** The address of the account that issued the balances. */
+    account: string
+    /**
+     * Total amounts issued to addresses not excluded, as a map of currencies
+     * to the total value issued.
+     */
+    obligations?: { [currency: string]: string }
+    /**
+     * Amounts issued to the hotwallet addresses from the request. The keys are
+     * addresses and the values are arrays of currency amounts they hold.
+     */
+    balances?: { [address: string]: GatewayBalance[] }
+    /**
+     * Total amounts held that are issued by others. In the recommended
+     * configuration, the issuing address should have none.
+     */
+    assets?: { [address: string]: GatewayBalance[] }
+    /**
+     * The identifying hash of the ledger version that was used to generate
+     * this response.
+     */
+    ledger_hash?: string
+    /**
+     * The ledger index of the ledger version that was used to generate this
+     * response.
+     */
+    ledger_current_index?: number
+    /**
+     * The ledger index of the current in-progress ledger version, which was
+     * used to retrieve this information.
+     */
+    ledger_index?: number
+  }
+}