xrpl 1.0.0-mpt-beta

package/src/client/partialPayment.ts

@@ -0,0 +1,173 @@
+import BigNumber from 'bignumber.js'
+import { decode } from 'ripple-binary-codec'
+
+import type {
+  AccountTxResponse,
+  TransactionEntryResponse,
+  TransactionStream,
+  TxResponse,
+} from '..'
+import type { Amount, IssuedCurrency, MPTAmount } from '../models/common'
+import type { RequestResponseMap } from '../models/methods'
+import { BaseRequest, BaseResponse } from '../models/methods/baseMethod'
+import { PaymentFlags, Transaction, isMPTAmount } from '../models/transactions'
+import type { TransactionMetadata } from '../models/transactions/metadata'
+import { isFlagEnabled } from '../models/utils'
+
+const WARN_PARTIAL_PAYMENT_CODE = 2001
+
+function amountsEqual(amt1: Amount, amt2: Amount): boolean {
+  if (typeof amt1 === 'string' && typeof amt2 === 'string') {
+    return amt1 === amt2
+  }
+
+  if (typeof amt1 === 'string' || typeof amt2 === 'string') {
+    return false
+  }
+
+  if (isMPTAmount(amt1) && isMPTAmount(amt2)) {
+    const aValue = new BigNumber(amt1.value)
+    const bValue = new BigNumber(amt2.value)
+
+    return (
+      (amt1 as MPTAmount).mpt_issuance_id ===
+        (amt2 as MPTAmount).mpt_issuance_id && aValue.isEqualTo(bValue)
+    )
+  }
+
+  if (isMPTAmount(amt1) || isMPTAmount(amt2)) {
+    return false
+  }
+
+  const aValue = new BigNumber(amt1.value)
+  const bValue = new BigNumber(amt2.value)
+
+  return (
+    (amt1 as IssuedCurrency).currency === (amt2 as IssuedCurrency).currency &&
+    (amt1 as IssuedCurrency).issuer === (amt2 as IssuedCurrency).issuer &&
+    aValue.isEqualTo(bValue)
+  )
+}
+
+function isPartialPayment(
+  tx?: Transaction,
+  metadata?: TransactionMetadata | string,
+): boolean {
+  if (tx == null || metadata == null || tx.TransactionType !== 'Payment') {
+    return false
+  }
+
+  let meta = metadata
+  if (typeof meta === 'string') {
+    if (meta === 'unavailable') {
+      return false
+    }
+
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- binary-codec typing */
+    meta = decode(meta) as unknown as TransactionMetadata
+  }
+
+  const tfPartial =
+    typeof tx.Flags === 'number'
+      ? isFlagEnabled(tx.Flags, PaymentFlags.tfPartialPayment)
+      : tx.Flags?.tfPartialPayment
+
+  if (!tfPartial) {
+    return false
+  }
+
+  const delivered = meta.delivered_amount
+  const amount = tx.Amount
+
+  if (delivered === undefined) {
+    return false
+  }
+
+  return !amountsEqual(delivered, amount)
+}
+
+function txHasPartialPayment(response: TxResponse): boolean {
+  return isPartialPayment(response.result, response.result.meta)
+}
+
+function txEntryHasPartialPayment(response: TransactionEntryResponse): boolean {
+  return isPartialPayment(response.result.tx_json, response.result.metadata)
+}
+
+function accountTxHasPartialPayment(response: AccountTxResponse): boolean {
+  const { transactions } = response.result
+  const foo = transactions.some((tx) => isPartialPayment(tx.tx, tx.meta))
+  return foo
+}
+
+function hasPartialPayment<R extends BaseRequest, T = RequestResponseMap<R>>(
+  command: string,
+  response: T,
+): boolean {
+  /* eslint-disable @typescript-eslint/consistent-type-assertions -- Request type is known at runtime from command */
+  switch (command) {
+    case 'tx':
+      return txHasPartialPayment(response as TxResponse)
+    case 'transaction_entry':
+      return txEntryHasPartialPayment(response as TransactionEntryResponse)
+    case 'account_tx':
+      return accountTxHasPartialPayment(response as AccountTxResponse)
+    default:
+      return false
+  }
+  /* eslint-enable @typescript-eslint/consistent-type-assertions */
+}
+
+/**
+ * Checks a response for a partial payment.
+ *
+ * @param command - Command from the request, tells us what response to expect.
+ * @param response - Response to check for a partial payment.
+ */
+export function handlePartialPayment<
+  R extends BaseRequest,
+  T = RequestResponseMap<R>,
+>(command: string, response: T): void {
+  if (hasPartialPayment(command, response)) {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- We are checking dynamically and safely.
+    const warnings = (response as BaseResponse).warnings ?? []
+
+    const warning = {
+      id: WARN_PARTIAL_PAYMENT_CODE,
+      message: 'This response contains a Partial Payment',
+    }
+
+    warnings.push(warning)
+
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- We are checking dynamically and safely.
+    // @ts-expect-error -- We are checking dynamically and safely.
+    response.warnings = warnings
+  }
+}
+
+/**
+ * Check a transaction from a subscription stream for partial payment.
+ *
+ * @param stream - Stream Transaction to check for partial payment.
+ * @param log - The method used for logging by the connection (to report the partial payment).
+ */
+export function handleStreamPartialPayment(
+  stream: TransactionStream,
+  log: (id: string, message: string) => void,
+): void {
+  if (isPartialPayment(stream.transaction, stream.meta)) {
+    const warnings = stream.warnings ?? []
+
+    const warning = {
+      id: WARN_PARTIAL_PAYMENT_CODE,
+      message: 'This response contains a Partial Payment',
+    }
+
+    warnings.push(warning)
+
+    /* eslint-disable-next-line no-param-reassign -- Handles the case where there are no warnings */
+    stream.warnings = warnings
+
+    log('Partial payment received', JSON.stringify(stream))
+  }
+}

package/src/errors.ts

@@ -0,0 +1,159 @@
+/* eslint-disable max-classes-per-file -- Errors can be defined in the same file */
+/**
+ * Base Error class for xrpl.js. All Errors thrown by xrpl.js should throw
+ * XrplErrors.
+ *
+ * @category Errors
+ */
+class XrplError extends Error {
+  public readonly name: string
+  public readonly message: string
+  public readonly data?: unknown
+
+  /**
+   * Construct an XrplError.
+   *
+   * @param message - The error message.
+   * @param data - The data that caused the error.
+   */
+  public constructor(message = '', data?: unknown) {
+    super(message)
+
+    this.name = this.constructor.name
+    this.message = message
+    this.data = data
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- `captureStackTrace` can be null in browsers
+    if (Error.captureStackTrace != null) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+
+  /**
+   * Converts the Error to a human-readable String form.
+   *
+   * @returns The String output of the Error.
+   */
+  public toString(): string {
+    let result = `[${this.name}(${this.message}`
+    if (this.data) {
+      result += `, ${JSON.stringify(this.data)}`
+    }
+    result += ')]'
+    return result
+  }
+
+  /**
+   * Console.log in node uses util.inspect on object, and util.inspect allows
+   * us to customize its output:
+   * https://nodejs.org/api/util.html#util_custom_inspect_function_on_objects.
+   *
+   * @returns The String output of the Error.
+   */
+  public inspect(): string {
+    return this.toString()
+  }
+}
+
+/**
+ * Error thrown when rippled responds with an error.
+ *
+ * @category Errors
+ */
+class RippledError extends XrplError {}
+
+/**
+ * Error thrown when xrpl.js cannot specify error type.
+ *
+ * @category Errors
+ */
+class UnexpectedError extends XrplError {}
+
+/**
+ * Error thrown when xrpl.js has an error with connection to rippled.
+ *
+ * @category Errors
+ */
+class ConnectionError extends XrplError {}
+
+/**
+ * Error thrown when xrpl.js is not connected to rippled server.
+ *
+ * @category Errors
+ */
+class NotConnectedError extends ConnectionError {}
+
+/**
+ * Error thrown when xrpl.js has disconnected from rippled server.
+ *
+ * @category Errors
+ */
+class DisconnectedError extends ConnectionError {}
+
+/**
+ * Error thrown when rippled is not initialized.
+ *
+ * @category Errors
+ */
+class RippledNotInitializedError extends ConnectionError {}
+
+/**
+ * Error thrown when xrpl.js times out.
+ *
+ * @category Errors
+ */
+class TimeoutError extends ConnectionError {}
+
+/**
+ * Error thrown when xrpl.js sees a response in the wrong format.
+ *
+ * @category Errors
+ */
+class ResponseFormatError extends ConnectionError {}
+
+/**
+ * Error thrown when xrpl.js sees a malformed transaction.
+ *
+ * @category Errors
+ */
+class ValidationError extends XrplError {}
+
+/**
+ * Error thrown when a client cannot generate a wallet from the testnet/devnet
+ * faucets, or when the client cannot infer the faucet URL (i.e. when the Client
+ * is connected to mainnet).
+ *
+ * @category Errors
+ */
+class XRPLFaucetError extends XrplError {}
+
+/**
+ * Error thrown when xrpl.js cannot retrieve a transaction, ledger, account, etc.
+ * From rippled.
+ *
+ * @category Errors
+ */
+class NotFoundError extends XrplError {
+  /**
+   * Construct an XrplError.
+   *
+   * @param message - The error message. Defaults to "Not found".
+   */
+  public constructor(message = 'Not found') {
+    super(message)
+  }
+}
+
+export {
+  XrplError,
+  UnexpectedError,
+  ConnectionError,
+  RippledError,
+  NotConnectedError,
+  DisconnectedError,
+  RippledNotInitializedError,
+  TimeoutError,
+  ResponseFormatError,
+  ValidationError,
+  NotFoundError,
+  XRPLFaucetError,
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export { Client, ClientOptions } from './client'
+
+export * from './models'
+
+export * from './utils'
+
+export { default as ECDSA } from './ECDSA'
+
+export * from './errors'
+
+export { FundingOptions } from './Wallet/fundWallet'
+export { Wallet } from './Wallet'
+
+export { walletFromSecretNumbers } from './Wallet/walletFromSecretNumbers'
+
+export { keyToRFC1751Mnemonic, rfc1751MnemonicToKey } from './Wallet/rfc1751'
+
+export * from './Wallet/signer'

package/src/models/common/index.ts

@@ -0,0 +1,162 @@
+export type LedgerIndex = number | ('validated' | 'closed' | 'current')
+
+export interface XRP {
+  currency: 'XRP'
+  issuer?: never
+}
+
+export interface IssuedCurrency {
+  currency: string
+  issuer: string
+}
+
+export type Currency = IssuedCurrency | XRP
+
+export interface IssuedCurrencyAmount extends IssuedCurrency {
+  value: string
+}
+
+export interface MPTAmount {
+  mpt_issuance_id: string
+  value: string
+}
+
+export type Amount = IssuedCurrencyAmount | MPTAmount | string
+
+export interface Balance {
+  currency: string
+  issuer?: string
+  value: string
+}
+
+export interface Signer {
+  Signer: {
+    Account: string
+    TxnSignature: string
+    SigningPubKey: string
+  }
+}
+
+export interface Memo {
+  Memo: {
+    MemoData?: string
+    MemoType?: string
+    MemoFormat?: string
+  }
+}
+
+export type StreamType =
+  | 'consensus'
+  | 'ledger'
+  | 'manifests'
+  | 'peer_status'
+  | 'transactions'
+  | 'transactions_proposed'
+  | 'server'
+  | 'validations'
+
+export interface PathStep {
+  account?: string
+  currency?: string
+  issuer?: string
+}
+
+export type Path = PathStep[]
+
+/**
+ * The object that describes the signer in SignerEntries.
+ */
+export interface SignerEntry {
+  /**
+   * The object that describes the signer in SignerEntries.
+   */
+  SignerEntry: {
+    /**
+     * An XRP Ledger address whose signature contributes to the multi-signature.
+     * It does not need to be a funded address in the ledger.
+     */
+    Account: string
+    /**
+     * The weight of a signature from this signer.
+     * A multi-signature is only valid if the sum weight of the signatures provided meets
+     * or exceeds the signer list's SignerQuorum value.
+     */
+    SignerWeight: number
+    /**
+     * An arbitrary 256-bit (32-byte) field that can be used to identify the signer, which
+     * may be useful for smart contracts, or for identifying who controls a key in a large
+     * organization.
+     */
+    WalletLocator?: string
+  }
+}
+
+/**
+ * This information is added to Transactions in request responses, but is not part
+ * of the canonical Transaction information on ledger. These fields are denoted with
+ * lowercase letters to indicate this in the rippled responses.
+ */
+export interface ResponseOnlyTxInfo {
+  /**
+   * The date/time when this transaction was included in a validated ledger.
+   */
+  date?: number
+  /**
+   * An identifying hash value unique to this transaction, as a hex string.
+   */
+  hash?: string
+  /**
+   * The sequence number of the ledger that included this transaction.
+   */
+  ledger_index?: number
+  /**
+   * @deprecated Alias for ledger_index.
+   */
+  inLedger?: number
+}
+
+/**
+ * One offer that might be returned from either an {@link NFTBuyOffersRequest}
+ * or an {@link NFTSellOffersRequest}.
+ *
+ * @category Responses
+ */
+export interface NFTOffer {
+  amount: Amount
+  flags: number
+  nft_offer_index: string
+  owner: string
+  destination?: string
+  expiration?: number
+}
+
+/**
+ * One NFToken that might be returned from an {@link NFTInfoResponse}
+ *
+ * @category Responses
+ */
+export interface NFToken {
+  nft_id: string
+  ledger_index: number
+  owner: string
+  is_burned: boolean
+  flags: number
+  transfer_fee: number
+  issuer: string
+  nft_taxon: number
+  nft_serial: number
+  uri: string
+}
+
+export interface AuthAccount {
+  AuthAccount: {
+    Account: string
+  }
+}
+
+export interface XChainBridge {
+  LockingChainDoor: string
+  LockingChainIssue: Currency
+  IssuingChainDoor: string
+  IssuingChainIssue: Currency
+}

package/src/models/index.ts

@@ -0,0 +1,16 @@
+/**
+ * LedgerEntry type definitions are exported in their own namespace to prevent
+ * collisions of the DepositPreauth SLE and Transaction. LedgerEntries are used
+ * by the client less often, and in most scenarios, like when parsing a
+ * response, the client won't need to import the type. If it is required to use
+ * a Ledger Entry, import `LedgerEntry`, and access individual ledger entry
+ * types on the `LedgerEntry` namespace.
+ */
+export * as LedgerEntry from './ledger'
+export {
+  setTransactionFlagsToNumber,
+  parseAccountRootFlags,
+} from './utils/flags'
+export * from './methods'
+export * from './transactions'
+export * from './common'

package/src/models/ledger/AMM.ts

@@ -0,0 +1,78 @@
+import { AuthAccount, Currency, IssuedCurrencyAmount } from '../common'
+
+import { BaseLedgerEntry, MissingPreviousTxnID } from './BaseLedgerEntry'
+
+export interface VoteSlot {
+  VoteEntry: {
+    Account: string
+    TradingFee: number
+    VoteWeight: number
+  }
+}
+
+/**
+ * The AMM object type describes a single Automated Market Maker (AMM) instance.
+ *
+ * @category Ledger Entries
+ */
+export default interface AMM extends BaseLedgerEntry, MissingPreviousTxnID {
+  LedgerEntryType: 'AMM'
+  /**
+   * The address of the special account that holds this AMM's assets.
+   */
+  Account: string
+  /**
+   * The definition for one of the two assets this AMM holds.
+   */
+  Asset: Currency
+  /**
+   * The definition for the other asset this AMM holds.
+   */
+  Asset2: Currency
+  /**
+   * Details of the current owner of the auction slot.
+   */
+  AuctionSlot?: {
+    /**
+     * The current owner of this auction slot.
+     */
+    Account: string
+    /**
+     * A list of at most 4 additional accounts that are authorized to trade at the discounted fee for this AMM instance.
+     */
+    AuthAccounts?: AuthAccount[]
+    /**
+     * The trading fee to be charged to the auction owner, in the same format as TradingFee.
+     * By default this is 0, meaning that the auction owner can trade at no fee instead of the standard fee for this AMM.
+     */
+    DiscountedFee: number
+    /**
+     * The time when this slot expires, in seconds since the Ripple Epoch.
+     */
+    Expiration: number
+    /**
+     * The amount the auction owner paid to win this slot, in LP Tokens.
+     */
+    Price: IssuedCurrencyAmount
+  }
+  /**
+   * The total outstanding balance of liquidity provider tokens from this AMM instance.
+   * The holders of these tokens can vote on the AMM's trading fee in proportion to their holdings,
+   * or redeem the tokens for a share of the AMM's assets which grows with the trading fees collected.
+   */
+  LPTokenBalance: IssuedCurrencyAmount
+  /**
+   * The percentage fee to be charged for trades against this AMM instance, in units of 1/100,000.
+   * The maximum value is 1000, for a 1% fee.
+   */
+  TradingFee: number
+  /**
+   * A list of vote objects, representing votes on the pool's trading fee.
+   */
+  VoteSlots?: VoteSlot[]
+  /**
+   * A bit-map of boolean flags. No flags are defined for the AMM object
+   * type, so this value is always 0.
+   */
+  Flags: 0
+}