xrpl 2.10.0 → 2.12.0-beta.0

package/src/models/transactions/common.ts

@@ -0,0 +1,320 @@
+/* eslint-disable max-lines-per-function -- Necessary for validateBaseTransaction */
+/* eslint-disable complexity -- Necessary for validateBaseTransaction */
+/* eslint-disable max-statements -- Necessary for validateBaseTransaction */
+import { TRANSACTION_TYPES } from 'ripple-binary-codec'
+
+import { ValidationError } from '../../errors'
+import {
+  Amount,
+  Currency,
+  IssuedCurrencyAmount,
+  Memo,
+  Signer,
+  XChainBridge,
+} from '../common'
+import { onlyHasFields } from '../utils'
+
+const MEMO_SIZE = 3
+
+function isMemo(obj: { Memo?: unknown }): boolean {
+  if (obj.Memo == null) {
+    return false
+  }
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
+  const memo = obj.Memo as Record<string, unknown>
+  const size = Object.keys(memo).length
+  const validData = memo.MemoData == null || typeof memo.MemoData === 'string'
+  const validFormat =
+    memo.MemoFormat == null || typeof memo.MemoFormat === 'string'
+  const validType = memo.MemoType == null || typeof memo.MemoType === 'string'
+
+  return (
+    size >= 1 &&
+    size <= MEMO_SIZE &&
+    validData &&
+    validFormat &&
+    validType &&
+    onlyHasFields(memo, ['MemoFormat', 'MemoData', 'MemoType'])
+  )
+}
+
+const SIGNER_SIZE = 3
+
+function isSigner(obj: unknown): boolean {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
+  const signerWrapper = obj as Record<string, unknown>
+
+  if (signerWrapper.Signer == null) {
+    return false
+  }
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS and Signer is previously unknown
+  const signer = signerWrapper.Signer as Record<string, unknown>
+  return (
+    Object.keys(signer).length === SIGNER_SIZE &&
+    typeof signer.Account === 'string' &&
+    typeof signer.TxnSignature === 'string' &&
+    typeof signer.SigningPubKey === 'string'
+  )
+}
+
+const XRP_CURRENCY_SIZE = 1
+const ISSUE_SIZE = 2
+const ISSUED_CURRENCY_SIZE = 3
+const XCHAIN_BRIDGE_SIZE = 4
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+}
+
+/**
+ * Verify the form and type of an IssuedCurrency at runtime.
+ *
+ * @param input - The input to check the form and type of.
+ * @returns Whether the IssuedCurrency is properly formed.
+ */
+export function isCurrency(input: unknown): input is Currency {
+  return (
+    isRecord(input) &&
+    ((Object.keys(input).length === ISSUE_SIZE &&
+      typeof input.issuer === 'string' &&
+      typeof input.currency === 'string') ||
+      (Object.keys(input).length === XRP_CURRENCY_SIZE &&
+        input.currency === 'XRP'))
+  )
+}
+
+/**
+ * Verify the form and type of an IssuedCurrencyAmount at runtime.
+ *
+ * @param input - The input to check the form and type of.
+ * @returns Whether the IssuedCurrencyAmount is properly formed.
+ */
+export function isIssuedCurrency(
+  input: unknown,
+): input is IssuedCurrencyAmount {
+  return (
+    isRecord(input) &&
+    Object.keys(input).length === ISSUED_CURRENCY_SIZE &&
+    typeof input.value === 'string' &&
+    typeof input.issuer === 'string' &&
+    typeof input.currency === 'string'
+  )
+}
+
+/**
+ * Verify the form and type of an Amount at runtime.
+ *
+ * @param amount - The object to check the form and type of.
+ * @returns Whether the Amount is properly formed.
+ */
+export function isAmount(amount: unknown): amount is Amount {
+  return typeof amount === 'string' || isIssuedCurrency(amount)
+}
+
+/**
+ * Verify the form and type of an XChainBridge at runtime.
+ *
+ * @param input - The input to check the form and type of.
+ * @returns Whether the XChainBridge is properly formed.
+ */
+export function isXChainBridge(input: unknown): input is XChainBridge {
+  return (
+    isRecord(input) &&
+    Object.keys(input).length === XCHAIN_BRIDGE_SIZE &&
+    typeof input.LockingChainDoor === 'string' &&
+    isCurrency(input.LockingChainIssue) &&
+    typeof input.IssuingChainDoor === 'string' &&
+    isCurrency(input.IssuingChainIssue)
+  )
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface -- no global flags right now, so this is fine
+export interface GlobalFlags {}
+
+/**
+ * Every transaction has the same set of common fields.
+ */
+export interface BaseTransaction {
+  /** The unique address of the transaction sender. */
+  Account: string
+  /**
+   * The type of transaction. Valid types include: `Payment`, `OfferCreate`,
+   * `TrustSet`, and many others.
+   */
+  TransactionType: string
+  /**
+   * Integer amount of XRP, in drops, to be destroyed as a cost for
+   * distributing this transaction to the network. Some transaction types have
+   * different minimum requirements.
+   */
+  Fee?: string
+  /**
+   * The sequence number of the account sending the transaction. A transaction
+   * is only valid if the Sequence number is exactly 1 greater than the previous
+   * transaction from the same account. The special case 0 means the transaction
+   * is using a Ticket instead.
+   */
+  Sequence?: number
+  /**
+   * Hash value identifying another transaction. If provided, this transaction
+   * is only valid if the sending account's previously-sent transaction matches
+   * the provided hash.
+   */
+  AccountTxnID?: string
+  /** Set of bit-flags for this transaction. */
+  Flags?: number | GlobalFlags
+  /**
+   * Highest ledger index this transaction can appear in. Specifying this field
+   * places a strict upper limit on how long the transaction can wait to be
+   * validated or rejected.
+   */
+  LastLedgerSequence?: number
+  /**
+   * Additional arbitrary information used to identify this transaction.
+   */
+  Memos?: Memo[]
+  /**
+   * Array of objects that represent a multi-signature which authorizes this
+   * transaction.
+   */
+  Signers?: Signer[]
+  /**
+   * Arbitrary integer used to identify the reason for this payment, or a sender
+   * on whose behalf this transaction is made. Conventionally, a refund should
+   * specify the initial payment's SourceTag as the refund payment's
+   * DestinationTag.
+   */
+  SourceTag?: number
+  /**
+   * Hex representation of the public key that corresponds to the private key
+   * used to sign this transaction. If an empty string, indicates a
+   * multi-signature is present in the Signers field instead.
+   */
+  SigningPubKey?: string
+  /**
+   * The sequence number of the ticket to use in place of a Sequence number. If
+   * this is provided, Sequence must be 0. Cannot be used with AccountTxnID.
+   */
+  TicketSequence?: number
+  /**
+   * The signature that verifies this transaction as originating from the
+   * account it says it is from.
+   */
+  TxnSignature?: string
+  /**
+   * The network id of the transaction.
+   */
+  NetworkID?: number
+}
+
+/**
+ * Verify the common fields of a transaction. The validate functionality will be
+ * optional, and will check transaction form at runtime. This should be called
+ * any time a transaction will be verified.
+ *
+ * @param common - An interface w/ common transaction fields.
+ * @throws When the common param is malformed.
+ */
+export function validateBaseTransaction(common: Record<string, unknown>): void {
+  if (common.Account === undefined) {
+    throw new ValidationError('BaseTransaction: missing field Account')
+  }
+
+  if (typeof common.Account !== 'string') {
+    throw new ValidationError('BaseTransaction: Account not string')
+  }
+
+  if (common.TransactionType === undefined) {
+    throw new ValidationError('BaseTransaction: missing field TransactionType')
+  }
+
+  if (typeof common.TransactionType !== 'string') {
+    throw new ValidationError('BaseTransaction: TransactionType not string')
+  }
+
+  if (!TRANSACTION_TYPES.includes(common.TransactionType)) {
+    throw new ValidationError('BaseTransaction: Unknown TransactionType')
+  }
+
+  if (common.Fee !== undefined && typeof common.Fee !== 'string') {
+    throw new ValidationError('BaseTransaction: invalid Fee')
+  }
+
+  if (common.Sequence !== undefined && typeof common.Sequence !== 'number') {
+    throw new ValidationError('BaseTransaction: invalid Sequence')
+  }
+
+  if (
+    common.AccountTxnID !== undefined &&
+    typeof common.AccountTxnID !== 'string'
+  ) {
+    throw new ValidationError('BaseTransaction: invalid AccountTxnID')
+  }
+
+  if (
+    common.LastLedgerSequence !== undefined &&
+    typeof common.LastLedgerSequence !== 'number'
+  ) {
+    throw new ValidationError('BaseTransaction: invalid LastLedgerSequence')
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
+  const memos = common.Memos as Array<{ Memo?: unknown }> | undefined
+  if (memos !== undefined && !memos.every(isMemo)) {
+    throw new ValidationError('BaseTransaction: invalid Memos')
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
+  const signers = common.Signers as Array<Record<string, unknown>> | undefined
+
+  if (
+    signers !== undefined &&
+    (signers.length === 0 || !signers.every(isSigner))
+  ) {
+    throw new ValidationError('BaseTransaction: invalid Signers')
+  }
+
+  if (common.SourceTag !== undefined && typeof common.SourceTag !== 'number') {
+    throw new ValidationError('BaseTransaction: invalid SourceTag')
+  }
+
+  if (
+    common.SigningPubKey !== undefined &&
+    typeof common.SigningPubKey !== 'string'
+  ) {
+    throw new ValidationError('BaseTransaction: invalid SigningPubKey')
+  }
+
+  if (
+    common.TicketSequence !== undefined &&
+    typeof common.TicketSequence !== 'number'
+  ) {
+    throw new ValidationError('BaseTransaction: invalid TicketSequence')
+  }
+
+  if (
+    common.TxnSignature !== undefined &&
+    typeof common.TxnSignature !== 'string'
+  ) {
+    throw new ValidationError('BaseTransaction: invalid TxnSignature')
+  }
+  if (common.NetworkID !== undefined && typeof common.NetworkID !== 'number') {
+    throw new ValidationError('BaseTransaction: invalid NetworkID')
+  }
+}
+
+/**
+ * Parse the value of an amount, expressed either in XRP or as an Issued Currency, into a number.
+ *
+ * @param amount - An Amount to parse for its value.
+ * @returns The parsed amount value, or NaN if the amount count not be parsed.
+ */
+export function parseAmountValue(amount: unknown): number {
+  if (!isAmount(amount)) {
+    return NaN
+  }
+  if (typeof amount === 'string') {
+    return parseFloat(amount)
+  }
+  return parseFloat(amount.value)
+}

package/src/models/transactions/depositPreauth.ts

@@ -0,0 +1,68 @@
+/* eslint-disable complexity -- Necessary for validateDepositPreauth */
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * A DepositPreauth transaction gives another account pre-approval to deliver
+ * payments to the sender of this transaction. This is only useful if the sender
+ * of this transaction is using (or plans to use) Deposit Authorization.
+ *
+ * @category Transaction Models
+ */
+export interface DepositPreauth extends BaseTransaction {
+  TransactionType: 'DepositPreauth'
+  /** The XRP Ledger address of the sender to preauthorize. */
+  Authorize?: string
+  /**
+   * The XRP Ledger address of a sender whose preauthorization should be.
+   * revoked.
+   */
+  Unauthorize?: string
+}
+
+/**
+ * Verify the form and type of a DepositPreauth at runtime.
+ *
+ * @param tx - A DepositPreauth Transaction.
+ * @throws When the DepositPreauth is malformed.
+ */
+export function validateDepositPreauth(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Authorize !== undefined && tx.Unauthorize !== undefined) {
+    throw new ValidationError(
+      "DepositPreauth: can't provide both Authorize and Unauthorize fields",
+    )
+  }
+
+  if (tx.Authorize === undefined && tx.Unauthorize === undefined) {
+    throw new ValidationError(
+      'DepositPreauth: must provide either Authorize or Unauthorize field',
+    )
+  }
+
+  if (tx.Authorize !== undefined) {
+    if (typeof tx.Authorize !== 'string') {
+      throw new ValidationError('DepositPreauth: Authorize must be a string')
+    }
+
+    if (tx.Account === tx.Authorize) {
+      throw new ValidationError(
+        "DepositPreauth: Account can't preauthorize its own address",
+      )
+    }
+  }
+
+  if (tx.Unauthorize !== undefined) {
+    if (typeof tx.Unauthorize !== 'string') {
+      throw new ValidationError('DepositPreauth: Unauthorize must be a string')
+    }
+
+    if (tx.Account === tx.Unauthorize) {
+      throw new ValidationError(
+        "DepositPreauth: Account can't unauthorize its own address",
+      )
+    }
+  }
+}

package/src/models/transactions/enableAmendment.ts

@@ -0,0 +1,26 @@
+import { BaseTransaction } from './common'
+
+/**
+ * Transaction Flags for an EnableAmendment Transaction.
+ *
+ * @category Transaction Flags
+ */
+export enum EnableAmendmentFlags {
+  /** Support for this amendment increased to at least 80% of trusted validators starting with this ledger version. */
+  tfGotMajority = 0x00010000,
+  /** Support for this amendment decreased to less than 80% of trusted validators starting with this ledger version. */
+  tfLostMajority = 0x00020000,
+}
+
+/**
+ * Mark a change in the status of a proposed amendment when it gains majority, looses majority, or is enabled.
+ *
+ * @category Pseudo Transaction Models
+ */
+export interface EnableAmendment extends BaseTransaction {
+  TransactionType: 'EnableAmendment'
+  /** A unique identifier for the amendment. */
+  Amendment: string
+  /** The ledger index where this pseudo-transaction appears. */
+  LedgerSequence: number
+}

package/src/models/transactions/escrowCancel.ts

@@ -0,0 +1,45 @@
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * Return escrowed XRP to the sender.
+ *
+ * @category Transaction Models
+ */
+export interface EscrowCancel extends BaseTransaction {
+  TransactionType: 'EscrowCancel'
+  /** Address of the source account that funded the escrow payment. */
+  Owner: string
+  /**
+   * Transaction sequence (or Ticket  number) of EscrowCreate transaction that.
+   * created the escrow to cancel.
+   */
+  OfferSequence: number
+}
+
+/**
+ * Verify the form and type of an EscrowCancel at runtime.
+ *
+ * @param tx - An EscrowCancel Transaction.
+ * @throws When the EscrowCancel is Malformed.
+ */
+export function validateEscrowCancel(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Owner === undefined) {
+    throw new ValidationError('EscrowCancel: missing Owner')
+  }
+
+  if (typeof tx.Owner !== 'string') {
+    throw new ValidationError('EscrowCancel: Owner must be a string')
+  }
+
+  if (tx.OfferSequence === undefined) {
+    throw new ValidationError('EscrowCancel: missing OfferSequence')
+  }
+
+  if (typeof tx.OfferSequence !== 'number') {
+    throw new ValidationError('EscrowCancel: OfferSequence must be a number')
+  }
+}

package/src/models/transactions/escrowCreate.ts

@@ -0,0 +1,100 @@
+/* eslint-disable complexity -- Necessary for validateEscrowCreate */
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * Sequester XRP until the escrow process either finishes or is canceled.
+ *
+ * @category Transaction Models
+ */
+export interface EscrowCreate extends BaseTransaction {
+  TransactionType: 'EscrowCreate'
+  /**
+   * Amount of XRP, in drops, to deduct from the sender's balance and escrow.
+   * Once escrowed, the XRP can either go to the Destination address (after the.
+   * FinishAfter time) or returned to the sender (after the CancelAfter time).
+   */
+  Amount: string
+  /** Address to receive escrowed XRP. */
+  Destination: string
+  /**
+   * The time, in seconds since the Ripple Epoch, when this escrow expires.
+   * This value is immutable; the funds can only be returned the sender after.
+   * this time.
+   */
+  CancelAfter?: number
+  /**
+   * The time, in seconds since the Ripple Epoch, when the escrowed XRP can be
+   * released to the recipient. This value is immutable; the funds cannot move.
+   * until this time is reached.
+   */
+  FinishAfter?: number
+  /**
+   * Hex value representing a PREIMAGE-SHA-256 crypto-condition . The funds can.
+   * only be delivered to the recipient if this condition is fulfilled.
+   */
+  Condition?: string
+  /**
+   * Arbitrary tag to further specify the destination for this escrowed.
+   * payment, such as a hosted recipient at the destination address.
+   */
+  DestinationTag?: number
+}
+
+/**
+ * Verify the form and type of an EscrowCreate at runtime.
+ *
+ * @param tx - An EscrowCreate Transaction.
+ * @throws When the EscrowCreate is Malformed.
+ */
+export function validateEscrowCreate(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Amount === undefined) {
+    throw new ValidationError('EscrowCreate: missing field Amount')
+  }
+
+  if (typeof tx.Amount !== 'string') {
+    throw new ValidationError('EscrowCreate: Amount must be a string')
+  }
+
+  if (tx.Destination === undefined) {
+    throw new ValidationError('EscrowCreate: missing field Destination')
+  }
+
+  if (typeof tx.Destination !== 'string') {
+    throw new ValidationError('EscrowCreate: Destination must be a string')
+  }
+
+  if (tx.CancelAfter === undefined && tx.FinishAfter === undefined) {
+    throw new ValidationError(
+      'EscrowCreate: Either CancelAfter or FinishAfter must be specified',
+    )
+  }
+
+  if (tx.FinishAfter === undefined && tx.Condition === undefined) {
+    throw new ValidationError(
+      'EscrowCreate: Either Condition or FinishAfter must be specified',
+    )
+  }
+
+  if (tx.CancelAfter !== undefined && typeof tx.CancelAfter !== 'number') {
+    throw new ValidationError('EscrowCreate: CancelAfter must be a number')
+  }
+
+  if (tx.FinishAfter !== undefined && typeof tx.FinishAfter !== 'number') {
+    throw new ValidationError('EscrowCreate: FinishAfter must be a number')
+  }
+
+  if (tx.Condition !== undefined && typeof tx.Condition !== 'string') {
+    throw new ValidationError('EscrowCreate: Condition must be a string')
+  }
+
+  if (
+    tx.DestinationTag !== undefined &&
+    typeof tx.DestinationTag !== 'number'
+  ) {
+    throw new ValidationError('EscrowCreate: DestinationTag must be a number')
+  }
+}

package/src/models/transactions/escrowFinish.ts

@@ -0,0 +1,63 @@
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * Deliver XRP from a held payment to the recipient.
+ *
+ * @category Transaction Models
+ */
+export interface EscrowFinish extends BaseTransaction {
+  TransactionType: 'EscrowFinish'
+  /** Address of the source account that funded the held payment. */
+  Owner: string
+  /**
+   * Transaction sequence of EscrowCreate transaction that created the held.
+   * payment to finish.
+   */
+  OfferSequence: number
+  /**
+   * Hex value matching the previously-supplied PREIMAGE-SHA-256.
+   * crypto-condition of the held payment.
+   */
+  Condition?: string
+  /**
+   * Hex value of the PREIMAGE-SHA-256 crypto-condition fulfillment matching.
+   * the held payment's Condition.
+   */
+  Fulfillment?: string
+}
+
+/**
+ * Verify the form and type of an EscrowFinish at runtime.
+ *
+ * @param tx - An EscrowFinish Transaction.
+ * @throws When the EscrowFinish is Malformed.
+ */
+export function validateEscrowFinish(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Owner === undefined) {
+    throw new ValidationError('EscrowFinish: missing field Owner')
+  }
+
+  if (typeof tx.Owner !== 'string') {
+    throw new ValidationError('EscrowFinish: Owner must be a string')
+  }
+
+  if (tx.OfferSequence === undefined) {
+    throw new ValidationError('EscrowFinish: missing field OfferSequence')
+  }
+
+  if (typeof tx.OfferSequence !== 'number') {
+    throw new ValidationError('EscrowFinish: OfferSequence must be a number')
+  }
+
+  if (tx.Condition !== undefined && typeof tx.Condition !== 'string') {
+    throw new ValidationError('EscrowFinish: Condition must be a string')
+  }
+
+  if (tx.Fulfillment !== undefined && typeof tx.Fulfillment !== 'string') {
+    throw new ValidationError('EscrowFinish: Fulfillment must be a string')
+  }
+}