xrpl 2.10.0 → 2.12.0-beta.0

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
+  }
+}

package/src/models/methods/ripplePathFind.ts

@@ -0,0 +1,81 @@
+import { Amount, Path } from '../common'
+
+import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
+
+export interface SourceCurrencyAmount {
+  currency: string
+  issuer?: string
+}
+
+/**
+ * The `ripple_path_find` method is a simplified version of the path_find method
+ * that provides a single response with a payment path you can use right away.
+ * Expects a response in the form of a {@link RipplePathFindResponse}.
+ *
+ * @category Requests
+ */
+export interface RipplePathFindRequest
+  extends BaseRequest,
+    LookupByLedgerRequest {
+  command: 'ripple_path_find'
+  /** Unique address of the account that would send funds in a transaction. */
+  source_account: string
+  /** Unique address of the account that would receive funds in a transaction. */
+  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. Cannot be used
+   * with `source_currencies`.
+   */
+  send_max?: Amount
+  /**
+   * Array of currencies that the source account might want to spend. Each
+   * entry in the array should be a JSON object with a mandatory currency field
+   * and optional issuer field, like how currency amounts are specified.
+   */
+  source_currencies?: SourceCurrencyAmount[]
+}
+
+export interface RipplePathFindPathOption {
+  /** 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
+}
+
+/**
+ * Response expected from a {@link RipplePathFindRequest}.
+ *
+ * @category Responses
+ */
+export interface RipplePathFindResponse extends BaseResponse {
+  result: {
+    /**
+     * Array of objects with possible paths to take, as described below. If
+     * empty, then there are no paths connecting the source and destination
+     * accounts.
+     */
+    alternatives: RipplePathFindPathOption[]
+    /** Unique address of the account that would receive a payment transaction. */
+    destination_account: string
+    /**
+     * Array of strings representing the currencies that the destination
+     * accepts, as 3-letter codes like "USD" or as 40-character hex like
+     * "015841551A748AD2C1F76FF6ECB0CCCD00000000".
+     */
+    destination_currencies: string[]
+    destination_amount: Amount
+    full_reply?: boolean
+    id?: number | string
+    ledger_current_index?: number
+    source_account: string
+    validated: boolean
+  }
+}

package/src/models/methods/serverInfo.ts

@@ -0,0 +1,257 @@
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The `server_info` command asks the server for a human-readable version of
+ * various information about the rippled server being queried. Expects a
+ * response in the form of a {@link ServerInfoResponse}.
+ *
+ * @category Requests
+ */
+export interface ServerInfoRequest extends BaseRequest {
+  command: 'server_info'
+}
+
+export type ServerState =
+  | 'disconnected'
+  | 'connected'
+  | 'syncing'
+  | 'tracking'
+  | 'full'
+  | 'validating'
+  | 'proposing'
+
+export interface StateAccounting {
+  duration_us: string
+  transitions: string
+}
+
+export interface JobType {
+  job_type: string
+  per_second: number
+  peak_time?: number
+  avg_time?: number
+  in_progress?: number
+}
+
+// The states for validating and proposing do not exist in the field state_accounting
+// See https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/misc/NetworkOPs.cpp#L4545
+// https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/misc/NetworkOPs.h#L66
+export type StateAccountingFinal = Record<
+  Exclude<ServerState, 'validating' | 'proposing'>,
+  StateAccounting
+>
+
+/**
+ * Response expected from a {@link ServerInfoRequest}.
+ *
+ * @category Responses
+ */
+export interface ServerInfoResponse extends BaseResponse {
+  result: {
+    info: {
+      /**
+       * If true, this server is amendment blocked. If the server is not
+       * amendment blocked, the response omits this field.
+       */
+      amendment_blocked?: boolean
+      /** The version number of the running rippled version. */
+      build_version: string
+      /**
+       * Information on the most recently closed ledger that has not been
+       * validated by consensus. If the most recently validated ledger is
+       * available, the response omits this field and includes
+       * `validated_ledger` instead. The member fields are the same as the.
+       * `validated_ledger` field.
+       */
+      closed_ledger?: {
+        age: number
+        base_fee_xrp: number
+        hash: string
+        reserve_base_xrp: number
+        reserve_inc_xrp: number
+        seq: number
+      }
+      /**
+       * Range expression indicating the sequence numbers of the ledger
+       * versions the local rippled has in its database.
+       */
+      complete_ledgers: string
+      /**
+       * On an admin request, returns the hostname of the server running the
+       * rippled instance; otherwise, returns a single RFC-1751  word based on
+       * the node public key.
+       */
+      hostid: string
+      /**
+       * Amount of time spent waiting for I/O operations, in milliseconds. If
+       * this number is not very, very low, then the rippled server is probably
+       * having serious load issues.
+       */
+      io_latency_ms: number
+      /**
+       * The number of times (since starting up) that this server has had over
+       * 250 transactions waiting to be processed at once. A large number here
+       * may mean that your server is unable to handle the transaction load of
+       * the XRP Ledger network.
+       */
+      jq_trans_overflow: string
+      /**
+       * Information about the last time the server closed a ledger, including
+       * the amount of time it took to reach a consensus and the number of
+       * trusted validators participating.
+       */
+      last_close: {
+        /**
+         * The amount of time it took to reach a consensus on the most recently
+         * validated ledger version, in seconds.
+         */
+        converge_time_s: number
+        /**
+         * How many trusted validators the server considered (including itself,
+         * if configured as a validator) in the consensus process for the most
+         * recently validated ledger version.
+         */
+        proposers: number
+      }
+      /**
+       * (Admin only) Detailed information about the current load state of the
+       * server.
+       */
+      load?: {
+        /**
+         * (Admin only) Information about the rate of different types of jobs
+         * the server is doing and how much time it spends on each.
+         */
+        job_types: JobType[]
+        /** (Admin only) The number of threads in the server's main job pool. */
+        threads: number
+      }
+      /**
+       * The load-scaled open ledger transaction cost the server is currently
+       * enforcing, as a multiplier on the base transaction cost. For example,
+       * at 1000 load factor and a reference transaction cost of 10 drops of
+       * XRP, the load-scaled transaction cost is 10,000 drops (0.01 XRP). The
+       * load factor is determined by the highest of the individual server's
+       * load factor, the cluster's load factor, the open ledger cost and the
+       * overall network's load factor.
+       */
+      load_factor?: number
+      /**
+       * The network id of the server.
+       */
+      network_id?: number
+      /**
+       * Current multiplier to the transaction cost based on
+       * load to this server.
+       */
+      load_factor_local?: number
+      /**
+       * Current multiplier to the transaction cost being used by the rest of
+       * the network.
+       */
+      load_factor_net?: number
+      /**
+       * Current multiplier to the transaction cost based on load to servers
+       * in this cluster.
+       */
+      load_factor_cluster?: number
+      /**
+       * The current multiplier to the transaction cost that a transaction must
+       * pay to get into the open ledger.
+       */
+      load_factor_fee_escalation?: number
+      /**
+       * The current multiplier to the transaction cost that a transaction must
+       * pay to get into the queue, if the queue is full.
+       */
+      load_factor_fee_queue?: number
+      /**
+       * The load factor the server is enforcing, not including the open ledger
+       * cost.
+       */
+      load_factor_server?: number
+      /**
+       * The number of peer connections which were severed.
+       */
+      peer_disconnects?: string
+      /**
+       * The number of peer connections which were severed due to excess resource consumption.
+       */
+      peer_disconnects_resources?: string
+      network_ledger?: 'waiting'
+      /** How many other rippled servers this one is currently connected to. */
+      peers: number
+      /**
+       * Public key used to verify this server for peer-to-peer communications.
+       * This node key pair is automatically generated by the server the first
+       * time it starts up. (If deleted, the server can create a new pair of
+       * Keys.).
+       */
+      pubkey_node: string
+      /** Public key used by this node to sign ledger validations. */
+      pubkey_validator?: string
+      /**
+       * A string indicating to what extent the server is participating in the
+       * network.
+       */
+      server_state: ServerState
+      /**
+       * The number of consecutive microseconds the server has been in the
+       * current state.
+       */
+      server_state_duration_us: string
+      /**
+       * A map of various server states with information about the time the
+       * server spends in each. This can be useful for tracking the long-term
+       * health of your server's connectivity to the network.
+       */
+      state_accounting: StateAccountingFinal
+      /** The current time in UTC, according to the server's clock. */
+      time: string
+      /** Number of consecutive seconds that the server has been operational. */
+      uptime: number
+      /** Information about the most recent fully-validated ledger. */
+      validated_ledger?: {
+        /** The time since the ledger was closed, in seconds. */
+        age: number
+        /**
+         * Base fee, in XRP. This may be represented in scientific notation.
+         * Such as 1e-05 for 0.00005.
+         */
+        base_fee_xrp: number
+        /** Unique hash for the ledger, as hexadecimal. */
+        hash: string
+        /**
+         * Minimum amount of XRP (not drops) necessary for every account to.
+         * Keep in reserve .
+         */
+        reserve_base_xrp: number
+        /**
+         * Amount of XRP (not drops) added to the account reserve for each
+         * object an account owns in the ledger.
+         */
+        reserve_inc_xrp: number
+        /** The ledger index of the latest validated ledger. */
+        seq: number
+      }
+      /**
+       * Minimum number of trusted validations required to validate a ledger
+       * version. Some circumstances may cause the server to require more
+       * validations.
+       */
+      validation_quorum: number
+      /**
+       * Either the human readable time, in UTC, when the current validator
+       * list will expire, the string unknown if the server has yet to load a
+       * published validator list or the string never if the server uses a
+       * static validator list.
+       */
+      validator_list_expires?: string
+      validator_list?: {
+        count: number
+        expiration: 'never' | 'unknown' | string
+        status: 'active' | 'expired' | 'unknown'
+      }
+    }
+  }
+}

package/src/models/methods/serverState.ts

@@ -0,0 +1,77 @@
+import { BaseRequest, BaseResponse } from './baseMethod'
+import { JobType, ServerState, StateAccountingFinal } from './serverInfo'
+
+/**
+ * The `server_state` command asks the server for various machine-readable
+ * information about the rippled server's current state. The response is almost
+ * the same as the server_info method, but uses units that are easier to process
+ * instead of easier to read.
+ *
+ * @category Requests
+ */
+export interface ServerStateRequest extends BaseRequest {
+  command: 'server_state'
+}
+
+/**
+ * Response expected from a {@link ServerStateRequest}.
+ *
+ * @category Responses
+ */
+export interface ServerStateResponse extends BaseResponse {
+  result: {
+    state: {
+      amendment_blocked?: boolean
+      build_version: string
+      complete_ledgers: string
+      closed_ledger?: {
+        age: number
+        base_fee: number
+        hash: string
+        reserve_base: number
+        reserve_inc: number
+        seq: number
+      }
+      io_latency_ms: number
+      jq_trans_overflow: string
+      last_close: {
+        // coverage_time_s only exists for `server_info` requests. `server_state` is a "non human" api request,
+        // therefore the type is coverage_time
+        // See https://github.com/XRPLF/rippled/blob/83faf43140e27e5d6d6779eaa0ffb75c33d98029/src/ripple/app/misc/NetworkOPs.cpp#L2458
+        converge_time: number
+        proposers: number
+      }
+      load?: {
+        job_types: JobType[]
+        threads: number
+      }
+      load_base: number
+      load_factor: number
+      load_factor_fee_escalation?: number
+      load_factor_fee_queue?: number
+      load_factor_fee_reference?: number
+      load_factor_server?: number
+      peer_disconnects?: string
+      peer_disconnects_resources?: string
+      peers: number
+      pubkey_node: string
+      pubkey_validator?: string
+      server_state: ServerState
+      server_state_duration_us: string
+      state_accounting: StateAccountingFinal
+      time: string
+      uptime: number
+      validated_ledger?: {
+        age?: number
+        base_fee: number
+        close_time: number
+        hash: string
+        reserve_base: number
+        reserve_inc: number
+        seq: number
+      }
+      validation_quorum: number
+      validator_list_expires?: number
+    }
+  }
+}

package/src/models/methods/submit.ts

@@ -0,0 +1,94 @@
+import { Transaction } from '../transactions'
+
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The submit method applies a transaction and sends it to the network to be
+ * confirmed and included in future ledgers. Expects a response in the form of a
+ * {@link SubmitResponse}.
+ *
+ * @category Requests
+ */
+export interface SubmitRequest extends BaseRequest {
+  command: 'submit'
+  /** The complete transaction in hex string format. */
+  tx_blob: string
+  /**
+   * If true, and the transaction fails locally, do not retry or relay the
+   * transaction to other servers. The default is false.
+   */
+  fail_hard?: boolean
+}
+
+/**
+ * Response expected from a {@link SubmitRequest}.
+ *
+ * @category Responses
+ */
+export interface SubmitResponse extends BaseResponse {
+  result: {
+    /**
+     * Text result code indicating the preliminary result of the transaction,
+     * for example `tesSUCCESS`.
+     */
+    engine_result: string
+    /** Numeric version of the result code. */
+    engine_result_code: number
+    /** Human-readable explanation of the transaction's preliminary result. */
+    engine_result_message: string
+    /** The complete transaction in hex string format. */
+    tx_blob: string
+    /** The complete transaction in JSON format. */
+    tx_json: Transaction & { hash?: string }
+    /**
+     * The value true indicates that the transaction was applied, queued,
+     * broadcast, or kept for later. The value `false` indicates that none of
+     * those happened, so the transaction cannot possibly succeed as long as you
+     * do not submit it again and have not already submitted it another time.
+     */
+    accepted: boolean
+    /**
+     * The next Sequence Number available for the sending account after all
+     * pending and queued transactions.
+     */
+    account_sequence_available: number
+    /**
+     * The next Sequence number for the sending account after all transactions
+     * that have been provisionally applied, but not transactions in the queue.
+     */
+    account_sequence_next: number
+    /**
+     * The value true indicates that this transaction was applied to the open
+     * ledger. In this case, the transaction is likely, but not guaranteed, to
+     * be validated in the next ledger version.
+     */
+    applied: boolean
+    /**
+     * The value true indicates this transaction was broadcast to peer servers
+     * in the peer-to-peer XRP Ledger network.
+     */
+    broadcast: boolean
+    /**
+     * The value true indicates that the transaction was kept to be retried
+     * later.
+     */
+    kept: boolean
+    /**
+     * The value true indicates the transaction was put in the Transaction
+     * Queue, which means it is likely to be included in a future ledger
+     * version.
+     */
+    queued: boolean
+    /**
+     * The current open ledger cost before processing this transaction
+     * transactions with a lower cost are likely to be queued.
+     */
+    open_ledger_cost: string
+    /**
+     * The ledger index of the newest validated ledger at the time of
+     * submission. This provides a lower bound on the ledger versions that the
+     * transaction can appear in as a result of this request.
+     */
+    validated_ledger_index: number
+  }
+}