xrpl 2.9.1 → 2.11.0

package/src/models/methods/ledgerEntry.ts

@@ -0,0 +1,177 @@
+import { LedgerEntry } from '../ledger'
+
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+/**
+ * The `ledger_entry` method returns a single ledger object from the XRP Ledger
+ * in its raw format. Expects a response in the form of a {@link
+ * LedgerEntryResponse}.
+ *
+ * @example
+ * ```ts
+ * const ledgerEntry: LedgerEntryRequest = {
+ *   command: "ledger_entry",
+ *   ledger_index: 60102302,
+ *   index: "7DB0788C020F02780A673DC74757F23823FA3014C1866E72CC4CD8B226CD6EF4"
+ * }
+ * ```
+ *
+ * @category Requests
+ */
+export interface LedgerEntryRequest extends BaseRequest, LookupByLedgerRequest {
+  command: 'ledger_entry'
+  /**
+   * Retrieve an Automated Market Maker (AMM) object from the ledger.
+   * This is similar to amm_info method, but the ledger_entry version returns only the ledger entry as stored.
+   */
+  amm?: {
+    asset: {
+      currency: string
+      issuer?: string
+    }
+    asset2: {
+      currency: string
+      issuer?: string
+    }
+  }
+
+  /**
+   * If true, return the requested ledger object's contents as a hex string in
+   * the XRP Ledger's binary format. Otherwise, return data in JSON format. The
+   * default is false.
+   */
+  binary?: boolean
+
+  /*
+   * Only one of the following properties should be defined in a single request
+   * https://xrpl.org/ledger_entry.html.
+   *
+   * Retrieve any type of ledger object by its unique ID.
+   */
+  index?: string
+
+  /**
+   * Retrieve an AccountRoot object by its address. This is roughly equivalent
+   * to the an {@link AccountInfoRequest}.
+   */
+  account_root?: string
+
+  /** The object ID of a Check object to retrieve. */
+  check?: string
+
+  /**
+   * Specify a DepositPreauth object to retrieve. If a string, must be the
+   * object ID of the DepositPreauth object, as hexadecimal. If an object,
+   * requires owner and authorized sub-fields.
+   */
+  deposit_preauth?:
+    | {
+        /** The account that provided the preauthorization. */
+        owner: string
+        /** The account that received the preauthorization. */
+        authorized: string
+      }
+    | string
+
+  /**
+   * The DirectoryNode to retrieve. If a string, must be the object ID of the
+   * directory, as hexadecimal. If an object, requires either `dir_root` o
+   * Owner as a sub-field, plus optionally a `sub_index` sub-field.
+   */
+  directory?:
+    | {
+        /** If provided, jumps to a later "page" of the DirectoryNode. */
+        sub_index?: number
+        /** Unique index identifying the directory to retrieve, as a hex string. */
+        dir_root?: string
+        /** Unique address of the account associated with this directory. */
+        owner?: string
+      }
+    | string
+
+  /**
+   * The Escrow object to retrieve. If a string, must be the object ID of the
+   * escrow, as hexadecimal. If an object, requires owner and seq sub-fields.
+   */
+  escrow?:
+    | {
+        /** The owner (sender) of the Escrow object. */
+        owner: string
+        /** Sequence Number of the transaction that created the Escrow object. */
+        seq: number
+      }
+    | string
+
+  /**
+   * The Offer object to retrieve. If a string, interpret as the unique object
+   * ID to the Offer. If an object, requires the sub-fields `account` and `seq`
+   * to uniquely identify the offer.
+   */
+  offer?:
+    | {
+        /** The account that placed the offer. */
+        account: string
+        /** Sequence Number of the transaction that created the Offer object. */
+        seq: number
+      }
+    | string
+
+  /** The object ID of a PayChannel object to retrieve. */
+  payment_channel?: string
+
+  /**
+   * Object specifying the RippleState (trust line) object to retrieve. The
+   * accounts and currency sub-fields are required to uniquely specify the
+   * rippleState entry to retrieve.
+   */
+  ripple_state?: {
+    /**
+     * 2-length array of account Addresses, defining the two accounts linked by
+     * this RippleState object.
+     */
+    accounts: string[]
+    /** Currency Code of the RippleState object to retrieve. */
+    currency: string
+  }
+
+  /**
+   * The Ticket object to retrieve. If a string, must be the object ID of the
+   * Ticket, as hexadecimal. If an object, the `owner` and `ticket_sequence`
+   * sub-fields are required to uniquely specify the Ticket entry.
+   */
+  ticket?:
+    | {
+        /** The owner of the Ticket object. */
+        owner: string
+        /** The Ticket Sequence number of the Ticket entry to retrieve. */
+        ticket_sequence: number
+      }
+    | string
+
+  /**
+   * Must be the object ID of the NFToken page, as hexadecimal
+   */
+  nft_page?: string
+}
+
+/**
+ * Response expected from a {@link LedgerEntryRequest}.
+ *
+ * @category Responses
+ */
+export interface LedgerEntryResponse extends BaseResponse {
+  result: {
+    /** The unique ID of this ledger object. */
+    index: string
+    /** The ledger index of the ledger that was used when retrieving this data. */
+    ledger_current_index: number
+    /**
+     * Object containing the data of this ledger object, according to the
+     * ledger format.
+     */
+    node?: LedgerEntry
+    /** The binary representation of the ledger object, as hexadecimal. */
+    node_binary?: string
+    validated?: boolean
+  }
+}

package/src/models/methods/manifest.ts

@@ -0,0 +1,54 @@
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The `manifest` method reports the current "manifest" information for a given
+ * validator public key. The "manifest" is the public portion of that
+ * validator's configured token. Expects a response in the form of a {@link
+ * ManifestResponse}.
+ *
+ * @example
+ * ```ts
+ * const manifest: ManifestRequest = {
+ *  "command": "manifest",
+ *  "public_key": "nHUFE9prPXPrHcG3SkwP1UzAQbSphqyQkQK9ATXLZsfkezhhda3p"
+ * }
+ * ```
+ *
+ * @category Requests
+ */
+export interface ManifestRequest extends BaseRequest {
+  command: 'manifest'
+  /**
+   * The base58-encoded public key of the validator to look up. This can be the
+   * master public key or ephemeral public key.
+   */
+  public_key: string
+}
+
+/**
+ * Response expected from a {@link ManifestRequest}.
+ *
+ * @category Responses
+ */
+export interface ManifestResponse extends BaseResponse {
+  result: {
+    /**
+     * The data contained in this manifest. Omitted if the server does not have
+     *  A manifest for the public_key from the request.
+     */
+    details?: {
+      domain: string
+      ephemeral_key: string
+      master_key: string
+      seq: number
+    }
+    /**
+     * The full manifest data in base64 format. This data is serialized to
+     * binary before being base64-encoded. Omitted if the server does not have a
+     * manifest for the public_key from the request.
+     */
+    manifest?: string
+    /** The public_key from the request. */
+    requested: string
+  }
+}

package/src/models/methods/nftBuyOffers.ts

@@ -0,0 +1,37 @@
+import { NFTOffer } from '../common'
+
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+/**
+ * The `nft_buy_offers` method retrieves all of buy offers for the specified
+ * NFToken.
+ *
+ * @category Requests
+ */
+export interface NFTBuyOffersRequest
+  extends BaseRequest,
+    LookupByLedgerRequest {
+  command: 'nft_buy_offers'
+  /**
+   * The unique identifier of an NFToken. The request returns buy offers for this NFToken.
+   */
+  nft_id: string
+}
+
+/**
+ * Response expected from an {@link NFTBuyOffersRequest}.
+ *
+ * @category Responses
+ */
+export interface NFTBuyOffersResponse extends BaseResponse {
+  result: {
+    /**
+     * A list of buy offers for the specified NFToken.
+     */
+    offers: NFTOffer[]
+    /**
+     * The token ID of the NFToken to which these offers pertain.
+     */
+    nft_id: string
+  }
+}

package/src/models/methods/nftHistory.ts

@@ -0,0 +1,113 @@
+import { ResponseOnlyTxInfo } from '../common'
+import { Transaction, TransactionMetadata } from '../transactions'
+
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+/**
+ * The nft_history method retrieves a list of transactions that involved the
+ * specified NFToken. Expects a response in the form of a {@link
+ * NFTHistoryResponse}.
+ *
+ * @category Requests
+ */
+export interface NFTHistoryRequest extends BaseRequest, LookupByLedgerRequest {
+  command: 'nft_history'
+  /**
+   * The unique identifier of an NFToken.
+   */
+  nft_id: 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 NFTHistoryTransaction {
+  /** 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 NFTHistoryRequest}.
+ *
+ * @category Responses
+ */
+export interface NFTHistoryResponse extends BaseResponse {
+  result: {
+    /**
+     * The unique identifier of an NFToken.
+     */
+    nft_id: 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: NFTHistoryTransaction[]
+    /**
+     * 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/nftInfo.ts

@@ -0,0 +1,25 @@
+import { NFToken } from '../common'
+
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+/**
+ * The `nft_info` method retrieves information about an NFToken.
+ *
+ * @category Requests
+ */
+export interface NFTInfoRequest extends BaseRequest, LookupByLedgerRequest {
+  command: 'nft_info'
+  /**
+   * The unique identifier of an NFToken.
+   */
+  nft_id: string
+}
+
+/**
+ * Response expected from an {@link NFTInfoResponse}.
+ *
+ * @category Responses
+ */
+export interface NFTInfoResponse extends BaseResponse {
+  result: NFToken
+}

package/src/models/methods/nftSellOffers.ts

@@ -0,0 +1,37 @@
+import { NFTOffer } from '../common'
+
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+/**
+ * The `nft_sell_offers` method retrieves all of sell offers for the specified
+ * NFToken.
+ *
+ * @category Requests
+ */
+export interface NFTSellOffersRequest
+  extends BaseRequest,
+    LookupByLedgerRequest {
+  command: 'nft_sell_offers'
+  /**
+   * The unique identifier of an NFToken. The request returns sell offers for this NFToken.
+   */
+  nft_id: string
+}
+
+/**
+ * Response expected from an {@link NFTSellOffersRequest}.
+ *
+ * @category Responses
+ */
+export interface NFTSellOffersResponse extends BaseResponse {
+  result: {
+    /**
+     * A list of sell offers for the specified NFToken.
+     */
+    offers: NFTOffer[]
+    /**
+     * The token ID of the NFToken to which these offers pertain.
+     */
+    nft_id: string
+  }
+}

package/src/models/methods/norippleCheck.ts

@@ -0,0 +1,82 @@
+import { LedgerIndex, ResponseOnlyTxInfo } from '../common'
+import { Transaction } from '../transactions'
+
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The `noripple_check` command provides a quick way to check the status of th
+ * default ripple field for an account and the No Ripple flag of its trust
+ * lines, compared with the recommended settings. Expects a response in the form
+ * of an {@link NoRippleCheckResponse}.
+ *
+ * @example
+ * ```ts
+ * const noRipple: NoRippleCheckRequest = {
+ *   "id": 0,
+ *   "command": "noripple_check",
+ *   "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
+ *    "role": "gateway",
+ *   "ledger_index": "current",
+ *   "limit": 2,
+ *   "transactions": true
+ * }
+ * ```
+ *
+ * @category Requests
+ */
+export interface NoRippleCheckRequest extends BaseRequest {
+  command: 'noripple_check'
+  /** A unique identifier for the account, most commonly the account's address. */
+  account: string
+  /**
+   * Whether the address refers to a gateway or user. Recommendations depend on
+   * the role of the account. Issuers must have Default Ripple enabled and must
+   * disable No Ripple on all trust lines. Users should have Default Ripple
+   * disabled, and should enable No Ripple on all trust lines.
+   */
+  role: 'gateway' | 'user'
+  /**
+   * If true, include an array of suggested transactions, as JSON objects,
+   * that you can sign and submit to fix the problems. Defaults to false.
+   */
+  transactions?: boolean
+  /**
+   * The maximum number of trust line problems to include in the results.
+   * Defaults to 300.
+   */
+  limit?: number
+  /** 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 to choose a
+   * ledger automatically.
+   */
+  ledger_index?: LedgerIndex
+}
+
+/**
+ * Response expected by a {@link NoRippleCheckRequest}.
+ *
+ * @category Responses
+ */
+export interface NoRippleCheckResponse extends BaseResponse {
+  result: {
+    /** The ledger index of the ledger used to calculate these results. */
+    ledger_current_index: number
+    /**
+     * Array of strings with human-readable descriptions of the problems.
+     * This includes up to one entry if the account's Default Ripple setting is
+     * not as recommended, plus up to limit entries for trust lines whose no
+     * ripple setting is not as recommended.
+     */
+    problems: string[]
+    /**
+     * If the request specified transactions as true, this is an array of JSON
+     * objects, each of which is the JSON form of a transaction that should fix
+     * one of the described problems. The length of this array is the same as
+     * the problems array, and each entry is intended to fix the problem
+     * described at the same index into that array.
+     */
+    transactions: Array<Transaction & ResponseOnlyTxInfo>
+  }
+}

package/src/models/methods/pathFind.ts

@@ -0,0 +1,116 @@
+import { Amount, Path } from '../common'
+
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+interface BasePathFindRequest extends BaseRequest {
+  command: 'path_find'
+  subcommand: string
+}
+
+/** Start sending pathfinding information. */
+export interface PathFindCreateRequest extends BasePathFindRequest {
+  subcommand: 'create'
+  /**
+   * Unique address of the account to find a path from. In other words, the.
+   * Account that would be sending a payment.
+   */
+  source_account: string
+  /** Unique address of the account to find a path to. */
+  destination_account: string
+  /**
+   * Currency Amount that the destination account would receive in a
+   * transaction.
+   */
+  destination_amount: Amount
+  /** Currency amount that would be spent in the transaction. */
+  send_max?: Amount
+  /**
+   * Array of arrays of objects, representing payment paths to check. You can
+   * use this to keep updated on changes to particular paths you already know
+   * about, or to check the overall cost to make a payment along a certain path.
+   */
+  paths?: Path[]
+}
+
+/** Stop sending pathfinding information. */
+export interface PathFindCloseRequest extends BasePathFindRequest {
+  subcommand: 'close'
+}
+
+/** Get the information of the currently-open pathfinding request. */
+export interface PathFindStatusRequest extends BasePathFindRequest {
+  subcommand: 'status'
+}
+
+/**
+ * The `path_find` method searches for a path along which a transaction can
+ * possibly be made, and periodically sends updates when the path changes over
+ * time. For a simpler version that is supported by JSON-RPC, see the
+ * `ripple_path_find` method.
+ *
+ * @category Requests
+ */
+export type PathFindRequest =
+  | PathFindCreateRequest
+  | PathFindCloseRequest
+  | PathFindStatusRequest
+
+export interface PathFindPathOption {
+  /** Array of arrays of objects defining payment paths. */
+  paths_computed: Path[]
+  /**
+   * Currency Amount that the source would have to send along this path for the.
+   * Destination to receive the desired amount.
+   */
+  source_amount: Amount
+  /**
+   * Destination Amount that the destination would receive along this path.
+   * If the `send_max` field is set, this field will be set.
+   */
+  destination_amount?: Amount
+}
+
+/**
+ * Response expected from a {@link PathFindRequest}.
+ *
+ * @category Responses
+ */
+export interface PathFindResponse extends BaseResponse {
+  result: {
+    /**
+     * Array of objects with suggested paths to take, as described below. If
+     * empty, then no paths were found connecting the source and destination
+     * accounts.
+     */
+    alternatives: PathFindPathOption[]
+    /** Unique address of the account that would receive a transaction. */
+    destination_account: string
+    /** Currency amount provided in the WebSocket request. */
+    destination_amount: Amount
+    /** Unique address that would send a transaction. */
+    source_account: string
+    /**
+     * If false, this is the result of an incomplete search. A later reply
+     * may have a better path. If true, then this is the best path found. (It is
+     * still theoretically possible that a better path could exist, but rippled
+     * won't find it.) Until you close the pathfinding request, rippled.
+     * Continues to send updates each time a new ledger closes.
+     */
+    full_reply: boolean
+    /**
+     * The ID provided in the WebSocket request is included again at this
+     * level.
+     */
+    id?: number | string
+    /**
+     * The value true indicates this reply is in response to a path_find close
+     * command.
+     */
+    closed?: true
+    /**
+     * The value true indicates this reply is in response to a `path_find`
+     * status command.
+     */
+    status?: true
+  }
+}

package/src/models/methods/ping.ts

@@ -0,0 +1,21 @@
+import type { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The ping command returns an acknowledgement, so that clients can test the
+ * connection status and latency. Expects a response in the form of a {@link
+ * PingResponse}.
+ *
+ * @category Requests
+ */
+export interface PingRequest extends BaseRequest {
+  command: 'ping'
+}
+
+/**
+ * Response expected from a {@link PingRequest}.
+ *
+ * @category Responses
+ */
+export interface PingResponse extends BaseResponse {
+  result: { role?: string; unlimited?: boolean }
+}

package/src/models/methods/random.ts

@@ -0,0 +1,23 @@
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The random command provides a random number to be used as a source of
+ * entropy for random number generation by clients. Expects a response in the
+ * form of a {@link RandomResponse}.
+ *
+ * @category Requests
+ */
+export interface RandomRequest extends BaseRequest {
+  command: 'random'
+}
+
+/**
+ * Response expected from a {@link RandomRequest}.
+ *
+ * @category Responses
+ */
+export interface RandomResponse extends BaseResponse {
+  result: {
+    random: string
+  }
+}